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This term in the 
previous edition 

Synchronous flow 
Asynchronous flow 
FME response 
RRN response 
indicator (for session 
control and data flow 
control) 



Has been replaced with this 
term in this edition 

Normal-flow 
Expedited-flow 
Definite response 1 
Definite response 2 
Command or reply 



In general, the term terminal, as used in this book, includes logical units, start-stop and BSC 
terminals, and local 3270 's. Where necessary (in describing basic-mode macro instructions), the 
meaning of terminal is restricted to mean only start-stop and BSC terminals and local 3270's- 
The term logical unit is understood to include BSC and local 3270's that are used in 
record-mode. Although these terminals are not true logical units, information that applies to 
logical units also applies to them. 
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A reminder in the description of the ARG field indicating that the value placed there when 
using NIB lists is not meaningful 

A note regarding the recovery procedure from a temporary storage shortage in the 
description of the SETLOGON macro instruction 
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format maps and DSECT descriptions in Appendix H 



PREFACE 



This book is a reference manual that contains detailed information on the macro 
instructions used with the Virtual Telecommunications Access Method (VTAM). 
The macro instructions are used to write the telecommunication portions of 
application porgrams that communicate with terminals through VTAM. This 
manual provides the specifications needed to code such programs. 

The beginning of this book lists the services provided by VTAM and indicates the 
macro instructions that are used to request each service. The beginning of the book 
also explains the conventions used throughout the book to indicate how the macro 
instructions are to be coded 

The rest of the book (except for the appendixes) contains detailed descriptions of 
the macro instructions, arranged in alphabetic order. Each description is presented 
in a fixed format with the information about each macro instruction presented in 
the same sequence. 

With few exceptions, VTAM macro instructions can be coded without regard for 
the particular operating sytem (DOS/VS, OS/VS1, or OS/VS2) under which the 
program will be running. When there is an exception to this, that exception is 
identified in the macro instruction description. 

Appendix A is a summary of the control block fields you use with each macro 
instruction. Once you have become familiar with the macro instructions, you will 
be able to use this appendix as a quick reference source. 

Appendix B indicates the line control characters that VTAM inserts into outgoing 
data and recognizes in incoming data. This information is shown for each BSC and 
start-stop device supported by VTAM. 

Appendixes C and D describe the return codes that are passed to the application 
program upon completion of each VTAM macro instruction. 

Appendixes E and F describe the operand formats and special forms of the GENCB, 
MODCB, SHOWCB, and TESTCB macro instructions. 

Appendix H shows the format of the application program control blocks and the 
DSECTs needed to access these control blocks with assembler instructions. 

Appendix I contains information relating to specific devices and the way the VTAM 
macro instructions should be used with the devices. 

The appendixes are followed by a glossary and an index. The index includes page 
numbers for all of the macro instruction operands and all of the fixed values that 
can be supplied with the operands. 

The reader should be familiar with Introduction to VTAM, GC27-6987, with 
Chapter 5 of VTAM Concepts and Planning, GC27-6998, and with those parts of 
the OS/ VS and DOS/VS Assembler Language GC33-4010, that explain the rules for 
coding assembler expressions. The reader should also be familiar with the 
characteristics of the devices with which the program will be communicating, with 
the line-control discipline (start-stop or BSC) that will be used with each one, and 
with teleprocessing concepts in general. Those unfamiliar with teleprocessing 
concepts can read Data Communications Primer, GC20-1668. The back of the 



Primer contains a telecommunications bibliography. 

A few portions of the VTAM language cannot be fully utilized without a working 
knowledge of the Network Control Program of the communications controller. If 
the reader is not familiar with this control program, a copy of the following 
publication should be obtained: 

IBM 3704 and 3705 Communications Controller: Network Control Program 
Generation and Utilities Guide and Reference Manual, GC30-3008. This publication 
is referred to as the NCP Generation and Utilities Guide in the remainder of this 
manual. 

Note: This edition of the VTAM Macro Language Reference Manual is to be used 
for planning purposes only until the applicable operating system becomes available. 
If changes are required at that time, they will be reported by revision or in 
Technical Newsletters. 
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FUNCTIONS PROVIDED BY THE VTAM MACRO INSTRUCTIONS 



The Virtual Telecommunications Access Method (VTAM) provides a program 
running under a virtual storage operating system with the ability to communicate 
with the terminals of a telecommunications network. The VTAM language 
described in this book is the set of macro instructions that are available to request 
this communication. 

VTAM provides four I/O macro instructions to communicate with a logical unit. 
These macro instructions (SEND, RECEIVE, RESETSR, and SESSIONC) are 
designated as record-mode macro instructions. The macro instructions used to 
communicate with BSC and start-stop terminals (READ, WRITE, RESET, 
SOLICIT, DO, LDO, and CHANGE) are designated as basic-mode macro instruc- 
tion. All other macro instructions described in this book can be used for both BSC 
and start-stop terminals and for logical units. 

The program using VTAM can request that VTAM. perform or initiate the 
following actions; the macro instruction used to request each one is shown in 
parentheses. 



Record-Mode 



Send a message or response to a logical unit (SEND). 

Receive a message or response from a logical unit (RECEIVE). 

Cancel a RECEIVE prematurely; switch a logical unit's continue-specific mode 
or continue-any mode (RESETSR). 

Send a clear, STSN, or SDT indicator to a logical unit and receive the response 
(SESSIONC). 



Basic-Mode 



Obtain data from one or a group of terminals and keep the data in VTAM 
buffers. Repeat this action until a specified amount of data has been received 
(SOLICIT). 

Using data already obtained from any terminal or from a specified terminal, 
move the data from VTAM buffers to an area in user storage (READ). 

Obtain data from a specific terminal and move it directly into user storage 
(READ). 

Transmit data from an area in program storage to a specified terminal (WRITE). 

Automatically follow an output operation with an input operation (WRITE). 

Cancel an I/O operation prematurely; reset an error lock set for a device 
(RESET). 



Common to Basic-Mode 
and Record-Mode 



• Check the completion status of any of the above activities (CHECK). 

• Execute any request defined by an RPL (EXECRPL). 

The I/O and I/O-related facilities listed above can be used by a program only after 
certain preparation has taken place. Control blocks must be built that describe the 
specific nature of the I/O operation to be performed. Since VTAM allows terminals 
to be used first by one program, then by another, connection between the program 
and the terminal must be established before any I/O activity can take place. The 
connection itself needs control blocks that describe the specific nature of that 
operation. 



The following VTAM services prepare for and support subsequent I/O activity. 

• Create a control block that contains the parameters of a connection or I/O 
operation (RPL). 

• Create a control block that identifies the program to VTAM and the 
telecommunications network (ACB). 

• Create a control block containing entry points for routines to be entered when 
certain events occur, such as attention interruptions, hardware errors, or a 
terminal's request for connection to the program (EXLST). 

• For each terminal, create a control block that contains information that affects 
subsequent communication with a particular terminal (NIB). 

• Generate any of the above control blocks during program execution rather than 
during program assembly; optionally generate them in dynamically allocated 
storage (GENCB). 

• Test, extract, or modify the parameters contained in these control blocks 
(TESTCB, SHOWCB, MODCB). 

• Identify the program to VTAM and the telecommunication network (OPEN). 

• Establish connection with a terminal or with a group of terminals (OPNDST). 

• Simulate a terminal's request for connection, so that a user-written routine that 
handles such requests will be invoked (SIMLOGON). 

• Allow logon requests to be directed at the application program, notify VTAM 
that the application program is no longer accepting logon requests, or indicate 
that the application program is once again accepting logon requests 
(SETLOGON). 

• Obtain the device characteristics or the logon message of a terminal requesting 
connection, or find out how many terminals are currently connected to the 
program and how many are waiting to become connected (INQUIRE). 

• Disconnect a terminal from the application program; optionally request that the 
disconnected terminal be connected to another program (CLSDST). 

• Disconnect the application program from VTAM and the telecommunications 
network (CLOSE). 



CATEGORIES OF VTAM MACRO INSTRUCTIONS 



Throughout the macro instruction descriptions and the appendixes of this book, 
you will encounter the terms manipulative, declarative, RPL-based, and ACB-based, 
macro instructions. These terms refer to categories of VTAM macro instructions. 
Figure 1 shows these categories and identifies the macro instructions that are 
included in each one. 



DECLARATIVE MACROS 



ACB 

EXLST 

RPL 

NIB 

LDO 



These build control blocks during program 
assembly. They are the only nonexecutable 
macro instructions. 



MANIPULATIVE MACROS 



GENCB 
MODCB 
SHOWCB 
TESTCB 



These build and manipulate control blocks 
during program execution. 



ACB-BASED MACROS 



OPEN 
CLOSE 



These open and close the application 
program's ACB. 



RPL-BASED MACROS 



OPNDST 
CLSDST 



These are used to request connection and 
data transfer. They all use an RPL, and, with 
the exception of CHECK, permit RPL 
modifications to be specified in the macro 
instruction itself. 



CONNECTION MACROS I/O MACROS 



SEND 
RECEIVE 
RESETSR 
SESSIONC 



MACROS THAT SUPPORT 
CONNECTION OR I/O 



SOLICIT 


CHANGE 


READ 


INQUIRE 


WRITE 


INTRPRET 


RESET 


SETLOGON 


DO 


SIMLOGON 




EXECRPL 




CHECK 



Figure 1 . Categories of VTAM Macro Instructions 



A NOTE ON VTAM-VSAM SIMILARITIES 



The Virtual Storage Access Method (VSAM) is an access method for direct access 
storage devices (DASDs). Like VTAM, it is available to programs running under 
virtual storage operating systems. There is considerable similarity between the two 
access methods with regard to control block names and fields, control block 
manipulation, and general approach to request handling. 

Both access methods use an ACB. The VTAM ACB essentially represents an 
application program. In VSAM, however, where the user has no need of an 
application program control block, the ACB represents the data set and is analogous 
to a DCB or DTF. Both types of ACBs are, however, objects of the OPEN macro 
instruction, and VSAM and VTAM ACBs can be opened with one macro 
instruction. 

Both types of ACB can contain pointers to an exit list. Both VSAM and VTAM exit 
lists contain addresses of routines to be entered when error conditions occur 
(LERAD and SYNAD exit-routines) and addresses of routines to be entered when 
special situations occur. 

Both access methods follow the same general I/O-request procedure: An I/O macro 
instruction is issued that indicates an RPL. The RPL in turn contains information 
about the request, such as the location of the I/O work area or whether the request 
is to be handled synchronously or asynchronously. 

Finally, both access methods use the same macro instructions— GENCB, MODCB, 
TESTCB, and SHOWCB-to generate and manipulate their respective ACB, EXLST, 
and RPL control blocks. 

Although the control blocks are similar in name, function, and (to some extent) 
content, the control blocks of one access method are not interchangeable with the 
corresponding control blocks of another. 

To make control blocks unique, a special VTAM operand is used when the control 
block is generated. By specifying AM=VTAM on the ACB, EXLST, or RPL macro 
instruction, the control block is generated in VTAM-compatible form. Omitting this 
operand causes a VSAM-compatible control block to be built. 



A NOTE ON CONTROL BLOCK MANIPULATION 



The application program control blocks (ACB, EXLST, RPL, and NIB) can be 
examined and modified two ways during program execution: The application 
program can use the manipulative macro instructions (GENCB, MODCB, TESTCB, 
or SHOWCB) or it can use IBM-supplied DSECTs. 

The manipulative macro instructions are essentially branches to access method 
routines that perform the control block manipulations specified on the macro. 
Their advantage is their ease of use and the freedom from reassembly they provide 
should control block formats be changed in future releases of VTAM or should you 
change from one operating system to another. 

The DSECTs provide labeled overlays for each of the control blocks for each 
operating system (the OS/VS1 and OS/VS2 ACB, EXLST, and RPL control blocks 
are identical, and the NIB is identical for all three operating systems). Their 
advantage is the improved performance (less system overhead) available through 
user-written assembler instructions. The general use of DSECTs is described in "The 
DSECT Instruction" in OS /VS and DOS/ VS Assembler Language, GC33-4010. 

The manipulative macro instructions are described alphabetically in this manual; 
tabulated information about them is contained in Appendixes E and F. The formats 
and DSECTs for the control blocks are described in Appendix H. 



HOW THE MACRO INSTRUCTIONS ARE DESCRIBED 

First, for an understanding of how macro instructions descriptions are arranged in 
this book, look at Figure 2. The balance of this section explains the conventions 
used in this figure. 

The Assembler Format Table Each macro instruction description contains a three-column table that shows how 

the macro instruction is to be coded. Since macro instructions are coded in the 
same format as assembler instructions, the three columns correspond to an 
assembler instruction's name, operation, and operand fields. This table is 
subsequently referred to as the macro instruction's assembler format table. 

Name: The macro instruction name provides a label for the macro instruction. The 
name, if used, can be specified as any symbolic name valid in the assembler 
language. 

Operation: This field contains the mnemonic operation code of the macro 
instruction. It is always coded exactly as shown. 

Operands: The operands provide information for the macro expansion program in 
the assembler. Generally, the information provided by the operands is made part of 
a parameter list provided to VTAM during program execution. All of the macro 
instruction's operands are indicated in the operands column of the assembler 
format table. 

Types of Operands: All operands are either keyword or positional operands. Most 
of the VTAM macro instruction operands are keyword operands. 

Keyword operands consist of a fixed character string (the operand keyword), an 
equal sign, and a single or multiple operand value. The presence of the equal sign 
distinguishes keyword from positional operands. Keyword operands do not have to 
be coded in the order shown in the operands column. For example, a macro having 
a LENGTH=dflfa length operand and an AREA=data area address operand (as 
indicated in the operands column) could be coded as either 

AREALEN= 132,AREA=WORK 

or 
AREA=WORK,AREALEN= 132 

Keyword operands must be separated by commas. If a keyword operand is omitted, 
the commas which would have been included with it are also omitted. 

There are a few instances in the VTAM macro instructions where more than one 
value can be coded after the keyword, but parentheses are required to do this. For 
example, an operand specified as 

FIELDS= field name | (field name,...) 

can be coded as 

FIELDS=RECLEN or FIELDS=(RECLEN) 

when only one field name is used. When more than one field name is used, 
however, the names must be enclosed in parentheses: 

FIELDS=(RECLEN,RTNCD,FDBK2) 



The above instruction is named 
and its basic purpose shown. 



An explanation tells what the 
macro instruction does. 



A table arranged in assembler 
format depicts the manner in 
which the macro instruction is 
coded. 



The table is followed by 
descriptions of each operand of 
the macro instruction. Each 
operand's function is explained. 



Following the explanation, special 
coding restrictions, examples of 
use, and special programming 
notes may appear. 



The operand descriptions are 
followed by an example of the 
macro instruction. 



The location of returned 
information is specified here, and 
the meaning of the returned 
information is explained. 
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WSSSKSSSm 


^^^^^^^1 


Operant! 









Format: 



Example. 



Notes: 



Example 



Return of Status Information 



If the macro instruction or operand applies only to logical units, 
"Record-mode Only" is shown. If the macro instruction or operand 
applies only to BSC or start-stop terminals, "Basic-mode Only" is 
shown. If neither is shown, the macro instruction or operand 
applies to all three types of terminal. 

I 



Figure 2. Basic Structure of the Descriptions of Each Macro 
8 



Positional operands must be coded in the exact order shown in the operands 
column. Positional operands are separated by commas, as are all operands, but if a 
positional operand is omitted, the surrounding commas must still be entered. For 
example, consider a macro that has three positional operands DCB, INOUT, and 
ACB1. If all three are used, they are coded as 

DCB 1, INOUT, ACB1 

but if only DCB1 and ACB1 are wanted, they are coded as 

DCB1„ACB1 

If the last positional operand or operands are omitted, the trailing comma or 
commas should not be coded. 

Operand Notation: A notational scheme is followed in the operands column to 
show how, when, and where operands can be coded. The notational symbols are 
never coded. 

• A vertical ( | ) means "exclusive or." For example A | B means that either A 
or B (but not both) should be coded. Such alternatives can also be shown aligned 
vertically, as shown in the next paragraph. 

• Braces ({}) are used to group alternative operand values. One of the alternative 
values enclosed with the braces must be chosen. The alternatives can be stacked 
vertically: 

(COND 
UNCOND 
LOCK 

or they can appear on one line: 

OPTCD={ COND | UNCOND | LOCK} 

Both expressions are equivalent. Note how the vertical bar is used to separate 
alternative values that appear on one line. When the grouping of alternatives on 
one line is unambiguous, the braces are usaully omitted: 

OPTCD=COND | UNCOND | LOCK 

• An underscored value means that if no value for that operand is selected, the 
macro will be expanded as though the underscored value had been coded. This 
alternative is called the assumed value, or default value. For example: 

OPTCD=COND | UNCOND | LOCK 

Here COND is the assumed value. If the OPTCD operand is omitted, 
OPTCD=COND is assumed by the assembler. 

• Brackets ([ ]) denote optional operands. In the following example, the ERET 
operand is optional. 

AM=VTAM 

[ERET=error routine address] 

• An ellipsis (...) indicates that whatever precedes it (either an operand value or an 
entire operand) can be repeated any number of times. An operand appearing as 

PROC=(processing option,...) 

could, for example, be coded as: 

PROC=(CONFTXT,DFASYX,RESPX) 

• Parentheses, equal-signs, and uppercase characters must be coded exactly as 
shown in the operands column. Lowercase words represent values that the user 
must supply. 



Comments and Continuation Lines: Comments may contain any characters valid in 
the assembler language. Comments can be continued on more than one card by 
placing an asterisk in column 1 as shown in the example below. In this publication, 
the comments field is not shown in the macro's assembler format table. 

Operands can also be continued on additional cards as shown below. Note that if 
the operands are not extended to column 71, they must be separated after a 
comma. The continuation character in column 72 can be any nonblank character, 
but it cannot be a character of an operand. Comments must by separated from 
operands by at least one blank. Throughout the rest of this publication, the 
continuation characters are not shown. 



Name 



Operation 



Operands 



LABEL 1 



LABEL2 



OP1 



OP2 



OPERAND 1 ,OPERAND2,OPERAND3 ,OPERX 
AND4,OPERAND5 THIS IS ONE WAY 



OPERAND l,OPERAND2, AND THIS X 
OPERAND3,OPERAND4, IS ANOTHER 

WAY 



' — column 1 



' — column 16 



column 72 



Operand Descriptions 



Following the assembler format table, each operand is named and described. Every 
operand description begins with an explanation of the operand's function. If the 
operand has more than one fixed value that can be supplied with it, the operand 
description also explains the effect that each value has on the action performed by 
the macro instruction. 



Operand Format: The operand description may include a description of the format 
in which the operand should be coded. This description is provided when the 
format is an exception to these general rules: 

• When a quantity is indicated (for example, RECLEN=data length), you can 
specify the value with unframed decimal integers, an expression that is equated 
to such a value, or the number of a register (enclosed by parentheses) that will 
contain the value when the macro instruction is executed. The value cannot 
exceed 32,767. Registers 1-12 can be specified for any RPL operand (that is, 
when an RPL address is being supplied). Register notation for all other operands 
is restricted to registers 2-12. 

• When an address is indicated (for example, ACB=acb address) and the macro 
instruction is a declarative macro instruction (see Figure 1), you can specify any 
relocatable expression that is valid for an A-type address constant. If the macro 
instruction is an RPL-based or ACB-based macro instruction, you can use any 
expression that is valid for an RX-type assembler instruction (such as an LA 
instruction). The value cannot exceed 32,767. Registers 1-12 can be specified for 
any RPL operand (that is, when an RPL address is being supplied). Register 
notation for all other operands is restricted to registers 2-12. 

If any of the terms used in the format descriptions are unclear, refer to the OS/VS 
and DOS/VS Assembler Language publication. 



10 



The valid notation for the operands of the manipulative macro instructions 
(GENCB, MODCB, SHOWCB, and TESTCB) are not as straightforward. The rules 
of syntax for the manipulative macro instructions are defined and tabulated in 
Appendix E. 

An example showing how the operand is coded or used may also be included in the 
operand description. Since there is an example elsewhere showing how the macro 
instruction as a whole might be coded, an operand example is provided only if the 
operand is unusually complex, or if its function can be better explained with an 
example. 



Examples 



Following the description of the macro instruction are one or more examples. 
These examples show possible ways that the macro and its operands might be 
coded. 



The way a macro can be specified can often be understood more readily from an 
example than it can from the assembler format table, since the latter must show all 
possible ways to specify the macro. A macro that appears to be complex in the 
assembler format table usually appears far simpler when it is actually coded. 



Return of Status Information 



All of the macro instructions post return codes in registers and most indicate status 
information in various control block fields when they are executed. Descriptions of 
this status information, when applicable, can be found at the end of the macro 
instruction description. Here you will often find references to Appendixes C and D, 
where the status information is tabulated. 
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ACB 



ACB— Create an Access Method Control Block 



The ACB identifies the application program to VTAM and to the teleprocessing 
network. 

Every application program must be defined by the installation before the program 
can use VTAM to communicate with the terminals throughout the network. The 
installation does this by creating an APPL entry for the application program in the 
resource definition table during VTAM definition. The application program's 
responsibility, then, is to create an ACB that indicates a particular APPL entry. The 
application program is identified by VTAM when that ACB is opened with the 
OPEN macro instruction. 

When the ACB is opened, requests for connection and then requests for I/O 
operations can be made (all connection and I/O requests indicate an ACB). When 
the ACB is closed (with the CLOSE macro instruction), requests can no longer be 
made, and any connections that were established are broken. 

Using the ACB, the application program can provide an address of a list of 
exit-routine addresses. The various routines represented in this list are invoked by 
VTAM when special events occur, such as error conditions, logon requests, and 
attention interruptions. The exit list pointed to in the ACB is created with the 
EXLST (or GENCB) macro instruction. 

Using the ACB, the application program can also prevent or allow VTAM to queue 
logon requests that are directed to the ACB. 

Every application program using VTAM must have an ACB. An application program 
could contain more than one ACB (thus breaking itself down into "subapplica- 
tions"), but each ACB must indicate a unique APPL entry. 

An ACB macro instruction causes an ACB to be built during program assembly. The 
control block is built on a fullword boundary. (The ACB can also be built during 
program execution with the GENCB macro instruction. See the GENCB macro for 
a description of this facility.) The ACB can be modified during program execution 
with the MODCB macro instruction, but only before it has been opened. The ACB 
cannot be modified while the ACB is open. 



Name 


Operation 


Operands 


[symbol] 


ACB 


AM=VTAM 

[ , APPLID=address of program's symbolic name] 

[ , PASSWD=password address] 

[ , EXLST=exit list address] 

f . MACRF= ( LOGON 1 NLOGON >1 



AM=VTAM 

Identifies the ACB built by this macro instruction as a VTAM ACB. This operand is 
required. 

APPLID=address of application program's symbolic name 

Links the ACB during OPEN processing with a particular APPL entry in the 
resource definition table. This both identifies the application program to VTAM 
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ACB 



and associates the application program with any options that might be indicated in 
the APPL entry. 

If you omit this operand, the APPLID field is set to 0. If this field is still set to 
when OPEN is executed, the job step name (in OS/VS1 and OS/VS2) or the job 
name specified on the program's EXEC statement (in DOS/VS) is used as the 
application program's symbolic name. 

Format: Expressions involving registers cannot be used with the ACB macro 
instruction. 

Note: The area pointed to by this operand must begin with a one-byte length 
indicator, followed by the application program 's symbolic name in EBCDIC. The 
length indicator specifies the length of the name. Any name that is longer than 8 is 
truncated to 8. You can either pad the name to the right with enough blanks to 
form an eight-byte name (length indicator of eight), or you can set the length 
indicator to the actual length of the name you are providing and let VTAMdo the 
padding. In the example at the end of this macro instruction description, the first 
method is used. 

PASSWD=password address 

Allows an application program to associate its ACB with an APPL entry that is 
password protected. If a password is included in an APPL entry, any application 
program wanting to link its ACB to that entry must specify the entry's password in 
the ACB. The two passwords are compared when the application program opens the 
ACB. If the passwords do not match, the ACB is not opened. (The purpose of this 
password protection is to prevent a program from running as one of the 
installation's predefined application programs without the authorization of the 
installation.) If you omit this operand, the PASSWD field is set to 0. 

Format: Expressions involving registers cannot be used with the ACB macro 
instruction. 

Note: The area pointed to by this operand must begin with a one-byte length 
indicator, followed by the EBCDIC password. The maximum length is 8. The 
truncation and use of the length indicator are the same as described above for the 
APPLID operand. 

EXLST=exit list address 

Links the ACB to an exit list containing addresses of routines to be entered when 
certain events occur. This list is created by an EXLST (or GENCB) macro 
instruction. See that macro for descriptions of these events. 

More than one ACB can indicate the same exit list. The use of an exit list is 
optional. If no exit list is used, the application program is not notified that the 
events described in the EXLST macro instruction occurred. 

Format: Expressions involving registers cannot be used with the ACB macro 
instruction. 

MACRF=LOGON | NLOGON 

Indicates whether or not the application program wants logon requests to be 
queued for it. MACRF=LOGON allows VTAM to queue logon requests for the 
application program as they occur. When SETLOGON (OPTCD=START) is issued, 
the scheduling of the LOGON exit-routine begins. SETLOGON (OPTCD=START) 
will not work unless MACRF=LOGON is specified for the ACB. MACRF= 
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ACB 



NLOGON indicates that no queuing of logon requests can occur. Any logon 
requests that may have been directed at your application program before the ACB 
was opened are canceled. MACRF=NLOGON serves to notify all application 
programs issuing INQUIRE (OPTCD=APPSTAT) that logon requests cannot be 
directed at the ACB. 

A logon request is a request issued by (or on behalf of) a terminal and directed at 
an application program; it in effect asks that application program to connect the 
application program to the terminal. A queued logon request cannot be satisfied 
until the application program issues an OPNDST macro instruction having an 
ACCEPT option code in effect for its RPL. This causes the application program to 
become connected to the terminal. 

If the ACB's EXLST operand indicates an exit list containing the address of a 
LOGON exit-routine (see EXLST macro), that routine is entered whenever a logon 
request is queued. This routine can issue the OPNDST macro instruction to request 
connection with the terminal and satisfy the logon request. 



ACB Fields Not Set by the 
Application Program 



The following ACB fields are set by VTAM when OPEN processing is completed, 
and cannot be set by the application program. The use of these fields is more fully 
explained in the OPEN and CLOSE macro instructions. 



Field Name Contents 

OFLAGS Indicates whether or not the ACB has been opened success- 

fully. By specifying OFLAGS=OPEN on a TESTCB macro 
instruction, you can determine if the ACB has been opened. 

ERROR Indicates why the ACB has not been opened or closed success- 

fully. You can use either SHOWCB or TESTCB to examine the 
codes in this field. The possible codes, along with their mean- 
ings, appear in the OPEN and CLOSE macro instruction 
descriptions. 



Example 



ACB1 ACB AM=VTAM,APPLID=NAME,PASSWD=PASFLD, 

MACRF=LOGON,EXLST=EXLST 1 



NAME 


DC 


X'08' 




DC 


CL8TAYROLL' 


PASFLD 


DC 


X'08' 




DC 


CL8'SECRET' 



ACB1 generates an ACB that will be associated with the PAYROLL APPL entry 
when the ACB is opened. SECRET is the password protecting that APPL entry. 
MACRF=LOGON means that terminals can issue logon requests to PAYROLL. 
When such requests are made, VTAM will note that ACB1 is the ACB providing 
access to the application program representing PAYROLL, and will invoke the 
LOGON exit-routine indicated in EXLST 1. 
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CHANGE-Change a Terminal's PROC Options or USERFLD Data (Basic-mode only) 

This macro instruction causes modifications to the PROC and USERFLD fields to 
become effective for a BSC or start-stop terminal. Since this means changing the 
ground rules under which all I/O requests for the terminal are processed, all pending 
I/O requests for the terminal are canceled when CHANGE is executed. 

When an OPNDST macro instruction is executed, the contents of these NIB fields 
are moved into internal VTAM control blocks. If the application program later 
wants to change the fields in effect for the terminal, altering the NIB to reflect 
these changes will not suffice since VTAM is referring to its internal control blocks, 
not to the NIB. Internal equivalents of the PROC and USERFLD fields must be 
changed as well. This latter function is provided by the CHANGE macro 
instruction. 

The RPL pointed to in the CHANGE macro instruction must indicate (in its NIB 
field) the NIB whose PROC or USERFLD field has been changed, and whose 
MODE field has been set to BASIC. The CID of the terminal must be set in the 
NIB's CID field. RPL fields (but not the NIB fields) can be set with the CHANGE 
macro instruction itself. 

To change the NIB fields, this procedure should be followed: 

1. Modify the fields in the NIB with MODCB. For example: 

MODCB AM=VTAM,NIB=NIB4,USERFLD=NYC, 

PROC=(TRANS,CONFTXT,MONITOR) 

2. Issue the CHANGE macro instruction to make these changes effective. 
CHANGE can simultaneously be used to make the RPL's NIB field point to the 
modified NIB, if it does not already do so: 

CHANGE RPL=RPL1,NIB=NIB4 



Name 


Operation 


Operands 


[symbol] 


CHANGE 


RPL=rpl address 

[ , rpl field name=new value] ... 



RPL=rpl address 

Indicates the RPL whose NIB field contains the address of the NIB that has been 
modified. 

rpl field name=new value 

Indicates an RPL field to be modified, and the new value that is to be contained 
within it. If you wish to avoid the possibility of program reassembly following 
future releases of VTAM, set the RPL field with MODCB macro instructions rather 
than with the CHANGE macro instruction. 

Format: For rpl field name, code the keyword of the RPL macro instruction 
operand that corresponds to the RPL field being modified. The new value can be 
any value that is valid for that operand in the RPL macro instruction, or it can 
indicate a register. 
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Although any RPL operand can be specified, the following operands apply to a 
CHANGE macro instruction: 

ACB=acb address 

Indicates the ACB used when the terminal was connected. 

NIB=nib address 

Indicates the NIB whose CID field identifies the terminal whose PROC or 
USERFLD attributes are being changed. 

ECB | EXIT=ecb or rpl exit-routine address 

Indicates the action to be taken by VTAM when an asynchronous (OPTCD=ASY) 
CHANGE macro instruction is completed. If EXIT is specified, the RPL 
exit-routine is scheduled. Otherwise the ECB is posted, and CHECK or WAIT must 
be used to determine when the posting occurs. See the RPL macro instruction for 
more information. 

OPTCD=SYN | ASY 

When the SYN option code is set, control is returned to the application program 
when the CHANGE operation has been completed. When ASY is set, control is 
returned as soon as VTAM has accepted the request. Once the operation is 
completed, the ECB is posted or the RPL exit-routine is scheduled, as indicated by 
the ECB-EXIT field. 

OPTCD=CS | CA 

When CA is set, data obtained from the terminal can satisfy a READ 
(OPTCD=ANY or OPTCD=SPEC) macro instruction. When CS is set, only READ 
(OPTCD=SPEC) macro instructions can obtain data from the terminal. 

Return of Status Information After the CHANGE operation is completed, the following RPL fields are set: 

The value 25 (decimal) is set in the REQ field, indicating a CHANGE request. 
The RTNCD and FDBK2 fields are set as indicated in Appendix C. 

Registers and 15 are also set as indicated in Appendix C. 
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CHECK— Check Request Status 



When asynchronous handling has been specified for a request (ASY option code in 
effect), the application program receives control when the request has been 
accepted by VTAM and the requested operation has been scheduled. A CHECK 
macro instruction must be issued for the RPL used for the request. (CHECK should 
not be issued for synchronous requests.) 

When CHECK is executed, the following actions occur: 

• The RPL, which was marked active when the request was accepted, is marked 
inactive. Once an RPL has been marked inactive (and issuing CHECK is the only 
way to do so for an asynchronous request), it can be reused by another request. 

• If the requested operation is not yet completed, CHECK suspends program 
execution until it is completed. If the RPL indicates an ECB, or if the ECB-EXIT 
field is not set, CHECK returns control to the application program when VTAM 
posts the ECB complete (see the ECB operand of the RPL macro). CHECK 
clears the ECB before returning control. 

• If the operation completed with a logical or other error, CHECK causes the 
LERAD or SYNAD exit-routine to be invoked, assuming that one is available. 
This action also occurs when CHECK is issued in any RPL exit-routine. 

CHECK returns the same register and register 1 5 return code that existed when 
the CHECK macro instruction was executed. There is one exception: If the RPL 
being checked indicates an RPL exit-routine, CHECK must not be executed before 
the operation represented by that RPL has completed and the RPL exit-routine has 
been scheduled. This situation can only occur when CHECK is issued outside of the 
RPL exit-routine. 



Name 


Operation 


Operands 


[symbol] 


CHECK 


RPL=rpl address 



RPL=rpl address 

Indicates the address of the RPL associated with the connection or I/O request 
whose completion status is being checked. 



Format: Register notation (for registers 1-12) is valid. 

Note: See the ECB and EXIT operands in the RPL macro instruction description 
for more information about the RPL exit routine and the ECB. 



Example 



CHK1 



CHECK 



RPL=RPL1 



If CHK1 is in the routine indicated by RPLl's EXIT field, and the operation 
requested via RPL1 ends with a logical or other error, the LERAD or SYNAD exit 
list routine is scheduled. 

If there is no RPL exit-routine for RPL1, CHK1 causes program execution to stop 
until the operation requested via RPL1 has ended. If the operation ends with a 
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logical or other error, CHK1 causes the LERAD or SYNAD exit-routine to be 
invoked. 

Return of Status Information When CHECK processing has been completed, registers and 1 5 are set as indicated 

in Appendix C. If an error occurred and a LERAD or SYNAD exit-routine was 
invoked, these registers contain the values set in them by the exit-routine. 
Otherwise, VTAM places a general return code in register 15 and a recovery action 
return code in register (see Figures C4 and C5 in Appendix C). 
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CLOSE-Close One or More ACBs 



There are three significant results of executing the CLOSE macro instruction: 

• VTAM no longer accepts any connection or I/O requests that refer to the ACB 
specified in the CLOSE macro. This ACB is effectively disconnected from 
VTAM. 

• VTAM no longer maintains the association between the APPL entry in the 
resource definition table and the ACB specified in this macro instruction. 
CLSDST (PASS) logon requests that are directed towards the application 
program cannot cause the LOGON exit-routine to be scheduled, but are queued 
awaiting the next OPEN. Insofar as terminals requesting logon are concerned, 
the portion of the application program represented by the ACB ceases to exist 
when CLOSE is executed. 

• VTAM breaks every connection that exists between the ACB and other 
terminals. Before CLOSE breaks a connection, all I/O activity is stopped and all 
pending I/O requests are canceled. (For logical units, a clear indicator is issued, 
and for BSC and start-stop terminals, a RESET operation is performed.) 

The CLOSE macro instruction can be applied to more than one ACB. CLOSE must 
be issued in the main program or in the LERAD or SYNAD exit-routine if the 
routine has been entered directly from the main program. Never issue CLOSE in the 
RPL exit-routine or in any of the other EXLST exit-routines. 

In OS/VS, where the privileged user can manage multiple tasks in the same 
application program, all I/O requests must be completed before CLOSE can be 
issued in the main part of the mother task. 



Name 



Operation 



Operands 



[symbol] 



CLOSE 



acb address[ , acb address] ... 



This form of CLOSE is valid in DOS/VS only. 



[symbol] 



CLOSE 



(acb address[ „ acb address] ...) 



This form of CLOSE is valid in OS/VS1 and OS/VS2 only. 



acb address 

Indicates the ACB that is to be disconnected from VTAM. 

Format: If more than one ACB is specified, separate each with a comma if the 
program is going to be ran under DOS/VS. Separate each ACB address with two 
commas if the program is going to be run under OS/VS. The parentheses for the 
OS/VS CLOSE can be omitted if only one address is coded. 

Note: One CLOSE macro instruction can be issued to close VSAM ACBs in 
addition to VTAM ACBs. DOS/VS users can also include DTFs with this macro 
instruction, and OS/VS1 and OS/VS2 users can also include DCBs. 
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Example 



CLOSE123 CLOSE 



ACB1,ACB2(7) (DOS/VS) 



Return of Status Information 



CLOSE 123 closes ACB1, ACB2, and the ACB whose address is in register 7. All 
terminals connected via these ACBs are disconnected. 



When control is returned to the instruction following the CLOSE macro, register 15 
indicates whether or not the CLOSE processing has been completed successfully. 
Successful completion (meaning that all ACBs specified in the macro instruction 
have been disconnected from VTAM) is indicated by a return code of (for 
DOS/VS users, register 15 is left unmodified). Unsuccessful completion is indicated 
by the following register 15 values: 



For DOS/VS 
nonzero 

For OS/VS 
4 



Meaning 

One or more ACBs (or DTFs or VSAM ACBs) were not 
successfully closed. 

Meaning 

One or more ACBs (or DCBs or VSAM ACBs) were not 
successfully closed. Depending on the specific type of error, 
the OFLAGS field may indicate that the "bad" ACB is closed 
even though CLOSE has failed (for example, the ACB may 
never have been opened). 



If unsuccessful completion is indicated, the application program can examine the 
OFLAGS field in each ACB to determine which ACB was not closed. If you use the 
OFLAGS=OPEN operand on a TESTCB macro instruction, an "equal" PSW 
condition code will result if the ACB was not closed. 

For each ACB, you can use either the SHOWCB or TESTCB macro instruction to 
check the ERROR field and determine the cause of the error. For example: 

SHOWCB AM=VTAM,ACB=ACB 1 ,FIELDS=ERROR,AREA=SHOWIT, 

LENGTH=4 

Note: // the ACB address specified in the CLOSE macro instruction does not 
indicate an ACB or lies beyond the addressable range of your application program, 
nothing is posted in the ACB's ERROR field. 

The value set in the ERROR field indicates the specific nature of the error 
encountered by CLOSE (all values except 48 apply to both DOS/VS and OS/VS): 

CLOSE successfully closed the ACB. 

8 A CLOSE macro instruction has already been successfully issued 

for this ACB (or the ACB has never been opened in the first 
place). 

42 (66) The ACB has been closed, but an apparent system error has 

prevented the successful disconnection of one or more of the 
terminals connected to your application. The fault is VTAM's, 
and IBM program systems representatives should be consulted. 
The terminals that could not be disconnected are not available to 
other application programs, and terminals for which you were 
requesting connection when CLOSE was executed will likewise be 
unavailable when they are released to you. You can notify the 
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system operator (during program execution) of the situation so 
that the operator can make the terminals available to other 
application programs. 

46 (70) CLOSE was not issued in the main program. OPEN and CLOSE 

cannot be issued in an exit-routine or in an RPL exit-routine. 

48 (72) CLOSE was not issued in a job step task or in a subtask within 

the VTAM region (OS/VS1 only). 

50 (80) VTAM is no longer included as part of the operating system. 



BC (188) The ACB is currently in the process of being opened, or is 

currently is the process of being closed by another CLOSE 
request. 
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CLSDST— Disconnect Terminals from the Application Program 



The CLSDST (close destination) macro instruction requests VTAM to break a 
connection between the application program and a specified terminal. CLSDST 
cancels any pending I/O requests for the terminal, and any unread data from the 
terminal is lost. 

The terminal to be disconnected is specified either with the ARG field or the NIB 
field of CLSDST'sRPL: 

• If the ARG field contains the CID of a terminal, that terminal is disconnected. 

• If the NIB field contains the address of a NIB, the terminal whose symbolic 
name has been placed in that NIB's NAME field is disconnected. 

(The RPL cannot contain both a CID and a pointer to a NIB, because the ARG 
and NIB fields occupy the same area in the RPL control block.) 

Using a CID is easier following normal communication with the terminal, since the 
CID is used by all of the I/O requests and thus should be readily available. Using a 
NIB address and symbolic name is necessary if you are issuing CLSDST for a 
terminal that was never connected to your application program. For example, you 
must issue CLSDST in order to reject a logon request, and you can cancel a pending 
OPNDST (OPTCD=ACCEPT) macro instruction by issuing CLSDST. In both of 
these situations, only the terminal's symbolic name is available to you. 

CLSDST with OPTCD=RELEASE causes a dial-line disconnection only if no other 
application program has requested connection with the terminal. 

If at the time CLSDST is executed, VTAM buffers hold data from the terminal, the 
data is not saved for the next application program that becomes connected to the 
terminal, but is discarded. 

The CLSDST macro instruction can optionally be used to request that VTAM 
reconnect terminals to another application program (specified by you) in addition 
to disconnecting them. This option is implemented by setting the PASS option 
code in CLSDST's RPL. If this option is used (it must be authorized by the 
installation), VTAM first disconnects the terminal and then generates a logon 
request for it. Your application program must indicate which application program is 
to receive the logon request. A logon message from a data area in your program can 
also be sent with the logon request. (The data area containing the logon message 
can be reused as soon as CLSDST has been completed.) 

If a logon request is going to be generated after the disconnection, the RPL's PASS 
option code must be set, and the RPL's AAREA field must point to the symbolic 
name of the receiving application program. This name must be placed in an 8-byte 
field, left justified, and padded to the right with blanks. If a logon message is also to 
be sent with the logon request, the AREA and RECLEN fields must indicate the 
location and length of the message. If a message is not to be sent, the RECLEN 
field must be set to 0. 

CLSDST (OPTCD=PASS) will fail if the receiving application program has not been 
activated, has opened its ACB with MACRF=NLOGON specified, or has issued 
SETLOGON (OPTCD=QUIESCE) and closed its logon request queue. However, 
CLSDST (OPTCD=PASS) will cause a logon request to be queued if the target 
application program has issued SETLOGON (OPTCD=STOP), even though this 
indicates that the application program temporarily does not want any logon 



22 



CLSDST 



requests directed at it. A logon request will also be queued if the application 
program has been activated but has not yet opened its ACB (if the ACB is later 
opened with MACRF=NLOGON, the logon request is dequeued). VTAM prevents 
such queuing if the logon request originates from the logical unit or via the network 
solicitor. But for logon requests generated by CLSDST (OPTCD=PASS), an 
INQUIRE macro instruction (OPTCD=APPSTAT) normally should be issued before 
CLSDST (OPTCD=PASS) is issued. The return code from INQUIRE will indicate 
the exact status of the receiving application program. 

If the RELEASE option code is used instead of the PASS option code, the terminal 
is simply disconnected as far as as the application program is concerned. If another 
application program has requested connection to the terminal, or if the installation 
indicated during VTAM definition that automatic logon requests are to be 
generated, VTAM reconnects the terminal to the appropriate application program. 

If an application program has completed its processing and is ready to disconnect 
all of the terminals connected to it, CLSDST need not be used. The CLOSE macro 
instruction may be used, since it disconnects all of the terminals connected via a 
given ACB (as though CLSDST with the RELEASE option had been issued for each 
one). 



Name 


Operation 


Operands 


[symbol] 


CLSDST 


RPL=rpl address 

[ , rpl field name=new value] ... 



RPL=rpl address 

Indicates the location of the RPL to be used during CLSDST processing. Either the 
ARG field of this RPL must contain a terminal's CID or the NIB field must be set 
to point to the NIB containing the symbolic name of the terminal. 

rpl field name=new value 

Indicates an RPL field to be modified, and the new value that is to be contained 
within it. If you wish to avoid the possibility of program reassembly following 
future releases of VTAM, set the RPL field with MODCB macro instructions rather 
than with the CLSDST macro instruction. 

Format: For rpl field name, code the keyword of the RPL macro instruction 
operand that corresponds to the RPL field being modified. ARG can also be coded. 
The new value can be any value that is valid for that operand in the RPL macro 
instruction, or it can indicate a register. The value supplied with the ARG keyword 
must indicate a register. 

Although any RPL operand can be specified, the following operands apply to a 
CLSDST macro instruction: 

ACB=acb address 

Indicates the ACB from which the terminal is to be disconnected. 

NIB=nib address 

Indicates the NIB whose NAME field identifies the terminal to be disconnected. If 
the NIB field does not indicate a NIB address, the ARG field must contain the 
terminal's CID. 
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Examples 



ARG=(register) 

Indicates the register that contains the CID of the terminal to be disconnected. This 
register notation must be used if the CID is to be placed into the ARG field with 
this CLSDST macro instruction. ARG and NIB provide two mutually exclusive 
methods of identifying the terminal. 

AREA=address of logon message 

Indicates the location of the data to be sent to the application program receiving 
the terminal. A logon message is sent only if OPTCD=PASS is set. 

RECLEN=length of logon message 

Indicates how many bytes of data are to be sent to the application program 
receiving the terminal. No data is sent if RECLEN is set to 0. 

AARE A=address of receiver's symbolic name 

Indicates the name of the application program that is to be connected to the 
terminal you are disconnecting. You can specify the application program that is to 
receive the terminal only if OPTCD=PASS is set. The name must be 8 bytes long 
and padded to the right with blanks. 

ECB | EXIT=ecb or rpl exit-routine address 

Indicates the action to be taken by VTAM when an asynchronous (OPTCD=ASY) 
CLSDST macro instruction is completed. The macro instruction is completed when 
I/O has been canceled and the terminal has been disconnected; completion does not 
depend on the receiving application program issuing OPNDST. If EXIT is specified, 
the RPL exit-routine is scheduled. Otherwise the ECB is posted, and CHECK or 
WAIT must be used to determine when posting occurs. See the RPL macro 
instruction for more information. 

OPTCD=SYN | ASY 

When SYN is set, control is returned to the application program when the CLSDST 
operation is completed. When ASY is set, control is returned as soon as VTAM has 
accepted the CLSDST request. Once the operation has been completed, the ECB is 
posted or the RPL exit-routine is scheduled, as indicated by the ECB-EXIT field. 

OPTCD=RELEASE | PASS 

When RELEASE is set, VTAM determines the identity of the terminal's next owner 
(if any). When PASS is set, a logon request is directed at the application program 
whose symbolic name is indicated in the A ARE A field of the RPL used by 
CLSDST. If the AREA and RECLEN fields are also set, a logon message is sent to 
the application program. The use of PASS must be authorized by the installation. 

CLl CLSDST RPL=RPL1, 

ACB=ACB1, 

NIB=NIB3, (TERMINAL TO BE DISCONNECTED) 

AAREA=APPLNAME, (APPLICATION TO RECEIVE LOGON REQUESTS) 

AREA=LGNMSG,RECLEN=60, (LOGON MESSAGE) 

ECB=POSTITl ,OPTCD=(ASY,PASS) 



POSTIT1 D F 

NIB3 NIB NAME=TERM1, 

APPLNAME DC CL8'PL0TTER' 

LGNMSG DC CL60'LOGON FROM STATION TERM1' 

CLl disconnects the terminal represented in NIB3 (TERM1) and generates a logon 
request for it; the logon request is directed at the application program named 
PLOTTER. This macro instruction also sends a 60-byte logon message from 
LGNMSG with the logon request. 
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CL2 CLSDST RPL=RPL2, 

ARG=(3), (TERMINAL TO BE DISCONNECTED) 
ECB=POSTIT2,OPTCD=(ASY,RELEASE) 

CL2 disconnects the terminal whose CID has been placed in register 3. Unlike the 
first example above, CL2 does not generate a logon request for a specified 
application program, nor does it send any logon message. 

CL3 CLSDST RPL=RPL3, 

NIB=NIB6, (TERMINAL TO BE DISCONNECTED) 

AAREA=APPLNAME, (APPLICATION TO RECEIVE LOGON MESSAGE) 
RECLEN=0, (NO LOGON MESSAGE) 

ECB=POSTIT3,OPTCD=(ASY,PASS) 

APPLNAME DC CL8TLOTTER' 

POSTIT3 DC F'O' 

NIB6 NIB NAME=TERM3 

CL3 disconnects the terminal represented by NIB6 (TERM3), and generates a logon 
request for it that is directed at the PLOTTER application program. Since the 
RECLEN field is being set to 0, no logon message is sent to PLOTTER. 

Return of Status Information After the CLSDST operation is completed, the following RPL fields are set: 

The value 3 1 (decimal) is set in the REQ field, indicating a CLSDST request. 
The RTNCD and FDBK2 fields are set as indicated in Appendix C. 

Registers and 15 are also set as indicated in Appendix C. 
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DO— Initiate LDO— Specified I/O Operations (Basic— mode only) 



If an application program uses logical device orders (LDOs) to request I/O 
operations, it must use the DO macro instruction to initiate the operations. The 
special I/O operations initiated with DO are described in the LDO macro 
instruction. 

The user of the DO macro instruction specifies an RPL whose AREA field contains 
the address of an LDO or list of LDOs, and whose ARG field contains the CID of 
the BSC or start-stop terminal that is to be the object of the I/O operations. 
Changes to the RPL can be specified in the DO macro instruction itself. 

When DO is completed, the AAREA field of the RPL indicates the address of the 
last LDO used by DO. If an error occurs, AAREA contains the address of the LDO 
that was being processed when the error occurred. 



Name 


Operation 


Operands 


[symbol] 


DO 


RPL=rpl address 

[, rpl field name=new value] ... 



RPL=rpl address 

Indicates the location of the RPL whose AREA field contains the address of an 
LDO or group of LDOs to be used, and whose ARG field contains the CID of the 
terminal that is to be the object of these LDOs. 

rpl field name=new value 

Indicates a field of the RPL to be modified and the new value that is to be 
contained within it. If you wish to avoid the possibility of program reassembly 
following future releases of VTAM, set the RPL field with MODCB macro 
instructions rather than with the DO macro instruction. 

Format: For rpl field name code the keyword of the RPL macro instruction 
operand that corresponds with the RPL field to be modified. ARG can also be 
coded. The new value can be any value that could have been supplied with the 
keyword had the operand been issued in an RPL macro instruction, or it can 
indicate a register. The value supplied for the ARG keyword must indicate a 
register. 

Although any RPL operand can be specified, the following operands apply to the 
DO macro instruction. 

ACB=acb address 

Indicates the ACB that was used when the terminal was connected. 

ARG=(register) 

Indicates the register containing the CID of the terminal. This register notation 
must be used when the CID is placed into the ARG field with this DO macro 
instruction. 

AREA=ldo address 

Indicates the LDO or chain of LDOs to be used by this macro instruction. 



26 



DO 



ECB | EXIT=ecb or rpl exit-routine address 

Indicates the action to be taken when an asynchronous (OPTCD=ASY) DO macro 
instruction is completed. The macro instruction is completed when the last LDO 
has been processed. If EXIT is specified, the RPL exit-routine is scheduled. 
Otherwise the ECB is posted, and CHECK or WAIT must be used to determine 
when the posting occurs. See the RPL macro instruction for more information. 

OPTCD=SYN|ASY 

When the SYN option code is set, control is returned to the application program 
when the DO operation has been completed. When ASY is set, control is returned 
as soon as VTAM has accepted the request. Once the DO operation has been 
completed, the ECB is posted or the RPL exit-routine is scheduled, as indicated by 
the ECB-EXIT field. 

OPTCD=CS|CA 

When CA is set, data obtained from the terminal can satisfy a READ (OPTCD= 
ANY or OPTCD=SPEC) macro instruction. When CS is set, only READ 
(OPTCD=SPEC) macro instructions can obtain data from the terminal. See the RPL 
macro instruction for more information. 



Example 



DOLDO 



DO 



RPL=RPL1, 
AREA=(2),ARG=(3), 
EXIT=DONE,OPTCD=(SPEC ,AS Y) 



Return of Status Information 



DOLDO initiates whatever operations are indicated by the LDO (or list of LDOs) 
currently pointed to by register 2. In this example, register 3 must contain the CID 
of the terminal to be involved in the LDO-specified I/O operation or operations. 
Since the ASY option code is specified, control is returned to the instruction 
following DOLDO before the operation is actually performed. Since EXIT is 
specified, the routine located at DONE will be scheduled when the DO macro 
instruction is completed. 

Once DO processing is finished, the following RPL fields are set: 

The address of the last LDO used by DO is placed in the AAREA field. 

When a NIB is used by OPNDST, the user has the option of specifying an 
arbitrary value in the USERFLD field of that NIB. When the DO macro 
instruction is subsequently issued for the terminal associated with that NIB, 
whatever had been placed in USERFLD by the user is placed in the USER field 
of the RPL by VTAM. 

If DO is processing a READ or READBUF LDO, the RECLEN field is set to 
indicate the number of bytes of data obtained from the terminal. 

The value 1 9 (decimal) is set in the REQ field, indicating a DO request. 

If DO is processing a READ or WRITE LDO, the SENSE field is set as indicated 
in Appendix C. 

If DO is processing a READ LDO, the FDBK field is set as indicated in 
Appendix C. 

The RTNCD and FDBK2 fields are set as indicated in Appendix C. 
Registers and 15 are also set as indicated in Appendix C. 



27 



EXECRPL 



EXECRPL— Execute a Request 



The EXECRPL macro instruction executes an RPL-defined request. The operation 
performed by EXECRPL depends on the request code that is set in the RPL's REQ 
field. If the request code for RECEIVE is set, for example, the effect of the 
EXECRPL macro instruction is identical to the effect of a RECEIVE macro 
instruction. The REQ field is described in the RPL macro instruction. 

The EXECRPL macro instruction is especially useful for retrying any RPL-based 
request that has failed (except CHECK or another EXECRPL macro). 

When a request fails for a temporary reason and the request might succeed if 
reissued, VTAM returns a recovery action return code of 8 in register and in the 
RPL's RTNCD field. The portion of the application program receiving control (the 
SYNAD exit-routine or the next sequential instrucion) has the address of the RPL 
available to it in register 1. The program can issue the EXECRPL to retry the 
request without examining the contents of the RPL. 



Name 


Operation 


Operands 


[symbol] 


EXECRPL 


RPL=rpl address 

[ , rpl field name=new value] ... 



RPL=rpl address 

Indicates the location of the RPL to be executed. 

rpl field name=new value 

Indicates a field of the RPL to be modified and the new value that is to be 
contained within it. If you wish to avoid the possibility of program reassembly 
following future releases of VTAM, set the RPL field with MODCB macro 
instructions rather than with the EXECRPL macro instruction. 

Format: For rpl field name, code the keyword of the RPL macro instruction 
operand that corresponds with the RPL field to be modified. The new value can be 
any value that could have been supplied with the keyword had the operand been 
issued in an RPL macro instruction, or it can indicate a register. 



Example 



RETRY1 EXECRPL RPL=(1) 

A SYNAD exit-routine has been entered for a retriable error (register is set to 8). 
The request is reexecuted as defined by the current contents of the RPL, which 
have not been altered since the first execution completed. 



Return of Status Information 



Once the EXECRPL macro instruction is completed, the action taken by VTAM 
depends on the type of request that EXECRPL has processed. The manner in which 
the application program is notified of completion (ECB or EXIT), the RPL fields 
and return codes that are returned, and the data areas (if any) that are used depend 
on the contents of the RPL when EXECRPL was executed. If the request is success- 
fully accepted or completed, then registers and 15 after the next sequential 
instruction after EXECRPL are set exactly as expected when the original request 
was issued. 
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EX LSI -Create an Exit List 



The EXLST macro instruction builds a list of routine addresses during program 
assembly. Each operand in this macro instruction represents an event in which an 
exit-routine is invoked by VTAM. The address supplied for each operand indicates 
the user-written routine to be given control when the event that it handles occurs. 
The SYNAD operand supplies the address of a routine that handles exception 
conditions (other than logical errors), the ATTN operand supplies the address of an 
attention-interruption handler, and so forth. 

When you examine your program listing, you may discover that the assembler has 
reserved space for exit list addresses that you never specified. Unspecified exits will 
not, however, be used by VTAM, and you cannot use MODCB to insert an address 
in a field you never specified in the EXLST (or GENCB) macro instruction. 

Two of the exit-routines are invoked by events initiated within the application 
program. The LERAD exit-routine is invoked when a request results in a logical 
error; the SYNAD exit-routine is invoked when a request results in other errors. If 
the error involves a synchronous request (one for which the SYN option code is in 
effect), the exit-routine is invoked when the error condition is detected. If the error 
involves an asynchronous request (ASY option code) that has been accepted, the 
exit-routine is not invoked until a CHECK macro instruction is issued for the 
request. (For asynchronous requests that are not accepted, the exit-routine is 
invoked when the error is detected.) 

The other exit-routines are invoked as a result of an event initiated outside of the 
application program. These exit-routines are scheduled at the time the event occurs. 
One routine, LOGON, falls into both categories. The programmer should be aware 
that if any synchronous requests are made in these exit-routines, neither the 
exit-routine nor the main part of the application program can receive control while 
the request is being completed. 

When the LERAD and SYNAD exit-routines are invoked, register 1 contains the 
address of the failing request's RPL. When the other exit-routines are invoked, 
register 1 contains the address of a parameter list. The contents of the parameter 
lists vary somewhat between exit-routines. The parameter lists are described in 
detail below and are summarized in Figure 3 near the end of the EXLST macro 
instruction description on page 35. 

For all exit-routines except LERAD and SYNAD, the last instruction must be a 
branch to the VTAM address that is in register 14 when the routine receives 
control. (For LERAD and SYNAD, the branch is optional if the exit -routine is not 
invoked by a macro instruction issued within an RPL exit-routine or other EXLST 
exit-routine.) The exit-routines are not provided with a save area for the general 
purpose registers. The application program may use and change registers as desired, 
but the register 14 address must be saved. The address of the exit list created by the 
EXLST macro instruction is placed in the EXLST field of an ACB by the 
application program (see the ACB macro instruction for details). More than one 
ACB can point to the same exit list, as long as the ACBs are all in the same object 
module. In this situation, however, the routines indicated in the exit list should be 
reenterable. All of the exit-routines must likewise reside in the same object module. 



The address of an EXLST containing a DFASY, RESP, or SCIP exit-routine address 
can also be placed in the EXLST field of a NIB. These NIB-oriented exit-routines 
are scheduled when input arrives from the logical unit represented by the NIB. If, 
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for example, DFASY input arrives from a logical unit, VTAM first determines 
whether a DFASY exit-routine was indicated when that logical unit was connected. 
If no RECEIVE is available, the exit-routine is scheduled. If no NIB-oriented 
DFASY exit-routine exists, VTAM determines whether an eligible RECEIVE is 
available or an ACB-oriented DFASY exit-routine was indicated when the ACB was 
opened. If so, it is scheduled. 

A few of the exit-routines apply only to BSC and start-stop terminals or only to 
logical units. These are noted below as "basic-mode only" or "record-mode only" 
respectively. 



Name 



Operation 



Operands 



[symbol] 



EXLST 



AM=VTAM 

[,LERAD= 

[,SYNAD= 

[,DFASY= 

[,RESP= 

[,SCIP= 

[,TPEND= 

[,RELREQ= 

[,LOGON= 

[,LOSTERM= 

[,ATTN= 



exit-routine address] 



AM=VTAM 

Identifies the exit list generated by this macro instruction as a VTAM exit list (as 
distinguished from a VSAM exit list). This operand is required. 

LERAD=exit-routine address 

Indicates the address of a routine that will be entered when the application program 
makes a connection or I/O request that results in a logical error. 

Generally, logical errors result when an RPL-based request is made that is 
inherently contradictory— like attempting to read data from an output-only device. 
(Errors that occur because of hardware malfunctions, for example, are not logical 
errors; they are handled by the SYNAD exit-routine.) 

If the SYN option code is in effect when the error occurs or if the request cannot 
be accepted due to a logical error, the LERAD exit-routine is entered immediately; 
otherwise if the ASY option code is in effect, the routine is not scheduled until a 
CHECK macro instruction is issued for the operation in which the error occurred. 
One exception: If the ASY option code is set, the request is accepted by VTAM, 
and then VTAM determines that it cannot post the RPL (perhaps because the ACB 
has been overwritten), VTAM abnormally terminates the application program. 

Before the LERAD exit-routine is given control, VTAM sets a recovery action 
return code of 20 or 24 (decimal) in register and in the RTNCD field of the RPL 
and sets a specific error return code in the FDBK2 field indicating the specific cause 
of the error. These codes are explained in Appendix C. 

If the application program has no LERAD exit-routine and a logical error occurs, 
VTAM simply returns control to the next sequential instruction. VTAM places a 
return code of 4 in register 15 and a recovery action return code in register 0. 
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If your application program issues CHECKs or synchronous requests in both the 
main program and in the exit-routines, the LERAD exit-routine may be reentered 
by VTAM. The routine may likewise be reentered if CHECKs or synchronous 
requests are issued in the LERAD routine itself. In these situations, you must insure 
that the exit list routine is reenterable. 

When the LERAD exit-routine returns control to VTAM, VTAM leaves registers 
and 1 5 intact so that the routine can pass information back in these registers to the 
main part of the application program. 

Registers Upon Entry: When the LERAD routine receives control, the general 
purpose registers contain the following: 

Register 0: A recovery action return code (see Appendix C). 

Register 1 : The address of the RPL associated with the request. If the recovery 
action return code in register is set to 24 (decimal), VTAM was unable to place 
an indicator in the FDBK2 field specifying the reason for the error. This happens 
in two cases: Either a macro has been issued whose RPL is already in use, or 
CHECK has been issued for a request whose RPL exit-routine has not yet been 
scheduled. See Appendix C for a description of the return codes placed in 
FDBK2. 

Register 13: The address of an 18-word save area supplied by you when the 
macro instruction was issued. If the exit-routine is going to return control via 
register 14, it must not change anything in the save area. This means that if any 
macro instructions are issued in the exit-routine, register 13 must first be loaded 
with the address of a new save area. Furthermore, before control is returned via 
register 14, register 13 must be restored with the value it had when the 
exit-routine was invoked. 

Register 14: The address in VTAM to which the LERAD exit-routine can branch 
when it is through processing. When the exit-routine branches to this address, 
VTAM handles the returning of control to the next sequential instruction in the 
application program following the request (or following the CHECK macro 
instruction issued for the request). The LERAD exit-routine can branch to any 
part of the main program because the routine is executed under the same system 
task control block as the main program. If the routine returns control to the 
next sequential instruction by branching on the register 14 address, VTAM 
restores the registers from the save area whose address is in register 13. 

Register 15: The address of the LERAD routine. 

SYNAD=exit-routine address 

Indicates the address of a routine that is entered if an unrecoverable input or 
output error (physical error) or other unusual condition occurs during an I/O 
operation. (Errors that result from invalid requests are handled by the LERAD 
exit-routine.) The SYNAD exit-routine is entered for all recovery action return 
codes of 4, 8, 12, and 16 (decimal). 

If the SYN option code is in effect when the error occurs or if the request cannot 
be accepted, the SYNAD exit-routine is entered immediately; otherwise, if the ASY 
option code is in effect, the routine is not invoked until a CHECK macro is issued 
for the operation in which the error occurred. 

The SYNAD exit-routine can examine the REQ field of the RPL and determine the 
type of request that caused the routine to be invoked. Each RPL-based macro 
instruction (except CHECK and EXEC RPL) has its own unique REQ code. These 
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codes are listed in the description of the RPL macro instruction. The SYNAD 
exit-routine can analyze the FDBK2 field and attempt to recover from the error. 

If the application program has no SYNAD exit-routine and a physical error occurs, 
VTAM simply returns control to the next sequential instruction with return codes 
in registers and 15. 

If your application program issues CHECKs or synchronous requests in both the 
main program and the exit-routines, the SYNAD exit-routine may be reentered by 
VTAM. The routine may likewise be reentered if CHECKs or synchronous requests 
are issued in the exit-routine itself. In these situations, you must ensure that the 
exit-routine is reenterable. 

When the SYNAD exit-routine returns control to VTAM, VTAM leaves registers 
and 15 intact; this enables the routine to pass information back in these registers to 
the main part of the application program. 

Registers Upon Entry: When the SYNAD routine receives control, the general 
purpose registers contain the following: 

Register 0: A recovery action return code (see Appendix C). 

Register 1: The address of the RPL associated with the request. 

Register 13: The address of an 18-word save area supplied by you when the 
macro instruction was issued. If the exit-routine is going to return control via 
register 14, it must not change anything in the save area. This means that if any 
macro instructions are issued in the exit-routine, register 13 must first be loaded 
with the address of a new save area. Furthermore, before control is returned via 
register 14, register 13 must be restored with the value it had when the 
exit-routine was invoked. 

Register 14: The address in VTAM to which the SYNAD exit-routine can branch 
when it is through processing. When the exit-routine branches to this address, 
VTAM handles the return of control to the next sequential instruction following 
the request (or following the CHECK macro issued for the request). The SYNAD 
exit-routine can branch to any part of main program. If the application program 
eventually returns to the next sequential instruction by branching on the register 
14 address, VTAM restores the registers from the same area whose address is in 
register 13. 

Register 15: The address of the SYNAD routine. 

DFASY=exit-routine address (Record-mode only) 

The EXLST containing a DFASY exit-routine address can be pointed to by a NIB, 
as well as by an ACB (see the EXLST operand of the NIB macro instruction). 

The DFASY operand indicates the address of a routine to be entered when 
asynchronous flow messages (such as QEC, RELQ, and RSHUTD indicators) arrive 
from a logical unit. VTAM handles the input in this manner: 

1. If a NIB-oriented DFASY exit-routine is available, it is scheduled. Otherwise— 

2. If input is already queued, this input is also queued. Otherwise— 

3. If a RECEIVE (OPTCD=SPEC,RTYPE=DFASY) is pending, the input is used to 
satisfy that RECEIVE. Otherwise- 

4. If the logical unit is in continue-specific (CS) mode, the input is queued. 
Otherwise— 
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5. If the DFASYX processing option is set and an ACB-oriented DFASY 
exit-routine is available, the exit-routine is scheduled. Otherwise— 

6. If a RECEIVE (OPTCD=ANY,RTYPE=DFASY) is pending, the input is used to 
satisfy that RECEIVE. Otherwise- 

7. The input is queued. 

The DFASY exit-routine provides a way for VTAM to notify the application 
program that asynchronous flow input has arrived. The application program 
could maintain an active RECEIVE macro instruction for this purpose, but the 
RECEIVE requires that an active RPL be committed before the input arrives, 
while the DFASY exit-routine does not. 

No RECEIVE is issued in the DFASY exit-routine to obtain the message. 
Instead, the exit-routine is passed the address of a read-only RPL. The read-only 
RPL fields are set as though a RECEIVE macro instruction (RTYPE=DFASY) 
had been issued. Do not issue CHECK for this RPL. 

Registers Upon Entry: When the DFASY exit-routine receives control, register 1 
contains the address of a 5-word parameter list: 

• The first word contains the address of an ACB. This ACB is the ACB of the 
application program to which the input data was sent. 

• The second word contains the CID of the terminal that sent the data. 

• The third word contains whatever has been placed in the USERFLD field of the 
NIB associated with that terminal. 

• The fourth word contains the number of bytes of data received by VTAM (since 
the length of asynchronous flow input is meaningless to the application program, 
this word should be ignored). 

• The fifth word contains the address of a VTAM-supplied read-only RPL. Other 
than the fact that it resides in read-only VTAM storage and cannot be used by an 
RPL-based macro instruction, the read-only RPL is identical to any other RPL. 
The application program can examine the read-only RPL fields with SHOWCB 
and TESTCB macro instructions or with assembler instructions. The read-only 
RPL feedback fields are set exactly as they would be following a RECEIVE 
macro instruction (RTYPE=DFASY) except that the REQ field is not set. 

Other general purpose registers contain the following: 

Register 14: The address in VTAM to which the DFASY routine must branch 
when it is through processing. VTAM will handle the return of control to the 
instruction following the request that resulted in the invocation of the DFASY 
routine. 

Register 15: The address of the DFASY routine. 

The contents of the remaining registers (0 and 2-13) are unpredictable. 

RESP=exit-routine address (Record-mode only) 

The EXLST containing the RESP exit-routine address can be pointed to by a NIB, 
as well as by an ACB (see the EXLST operand of the NIB macro instruction). 

The RESP operand indicates the address of a routine to be entered when responses 
arrive from a logical unit. VTAM handles the response in this manner: 

1. If a NIB-oriented exit-routine is available, it is scheduled. Otherwise— 

2. If responses are already queued, this response is also queued. Otherwise— 



33 



EXLST 



3. If a RECEIVE (OPTCD=SPEC,RTYPE=RESP) is pending, the response is used 
to satisfy that RECEIVE. Otherwise- 

4. If the logical unit is in continue-specific (CS) mode, the response is queued. 
Otherwise— 

5. If the RESPX processing option is set and an ACB-oriented RESP exit-routine is 
available, it is scheduled. Otherwise— 

6. If a RECEIVE (OPTCD=ANY,RTYPE=RESP) is pending, the response is used to 
satisfy that RECEIVE. Otherwise- 

7. The response is queued. 

The RESP exit-routine provides a way for VTAM to notify the application program 
that a response to a data message has arrived. The application program could 
maintain an active RECEIVE macro instruction for this purpose, but the RECEIVE 
macro instruction requires that an active RPL be committed before the response 
arrives, while the RESP exit-routine does not. 

No RECEIVE is issued in the RESP exit-routine to receive the response. Instead, 
the exit-routine is passed the address of a read-only RPL. The read-only RPL fields 
are set as though a RECEIVE macro instruction (RTYPE=RESP) has been issued. 
These fields can be examined with SHOWCB and TESTCB macro instructions or 
with assembler instructions like any other RPL. Do not issue CHECK for this RPL. 

Registers Upon Entry: When the RESP exit-routine receives control, the register 
contents are the same as those described above for the DFASY exit-routine. That 
is: 

• Register 1 contains the address of a parameter list containing the ACB address, 
the logical unit's CID and USERFLD data, the amount of input (since the length 
of a response is meaningless, this should be ignored), and the address of the 
read-only RPL. The parameter list is summarized in Figure 3. 

• Register 14 contains the address in VTAM to which the RESP exit-routine must 
return. 

• Register 15 contains the address of the RESP exit-routine. 

• The contents of the remaining registers (0 and 2-13) are unpredictable. 

SCIP=exit-routine address (Record-mode only) 

The EXLST containing the SCIP exit-routine address can be pointed to by a NIB, as 
well as by an ACB (see the EXLST operand of the MB macro instruction). 

The SCIP operand indicates the address of a routine to be scheduled when a 
request-recovery (RQR) indicator arrives from a logical unit. (The SCIP exit-routine 
is the only way the application program can be notified of the arrival of an RQR 
indicator.) The logical unit is automatically sent a normal response by VTAM 
regardless of whether a SCIP exit-routine is available. 

No RECEIVE macro instruction is used in the SCIP exit-routine. The address of a 
read-only RPL is provided in the SCIP parameter list. The application program 
should test the CONTROL field of the read-only RPL to verify that an RQR 
indicator has arrived (CONTROL=RQR for a TESTCB macro instruction). 

An RQR indicator may signify that the logical unit has discovered a discrepancy 
between the sequence number of its messages and the sequence number of the 
responses to those messages. The logical unit is in effect asking the application 
program to stop all message and response flow, establish the correct sequence 
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Figure 3. Parameter Lists for the EXLST Exit-Routines 



number, and resume message and response flow. These actions are accomplished by 
issuing clear, set-and-test-sequence-number (STSN) and start-data-traffic (SDT) 
indicators with a SESSIONC macro instruction. (The logical unit cannot accomplish 
this recovery procedure itself because only the application program can issue clear, 
STSN, and SDT indicators.) 

Registers Upon Entry: When the SCIP exit-routine receives control, the register 
contents are the same as those described above for the DFASY exit-routine. That 
is: 

• Register 1 contains the address of a parameter list containing the ACB address, 
the logical unit's CID and USERFLD data, the amount of input (since the length 
of an RQR indicator is meaningless, this should be ignored), and the address of 
the read-only RPL. 

• Register 14 contains the address in VTAM to which the SCIP exit-routine must 
return. 

• Register 15 contains the address of the SCIP exit-routine. 

• The contents of the remaining registers (0 and 2-13) are unpredictable. 



TPEND=exit-routine address 

Indicates the address of a routine to be entered when the network operator issues a 
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HALT command, or, in OS/VS1 and OS/VS2, when VTAM abnormally terminates. 
If the operator issues a HALT command to cause an ordinary ("non-quick") 
closedown, no new connection requests are permitted. If there is no TPEND 
exit-routine, the application program is not notified of the HALT command or 
pending termination except via the return codes resulting from pending and 
subsequent I/O requests. A TPEND exit-routine is strongly recommended. 

If the operator issued a HALT command to cause a quick closedown, or VTAM 
itself terminates, any operations in progress are allowed to complete. Requests not 
yet initiated by VTAM are canceled, however, and the RPL's FDBK2 field is posted 
to indicate the reason for their premature completion. In a quick closedown 
situation, the TPEND exit-routine cannot send or receive any data from the 
connected terminals, and can either issue CLSDST for each one, or disconnect them 
all with the CLOSE macro instruction. Note: CLOSE cannot be issued in an 
exit-routine, but the TPEND routine could cause a CLOSE in the main program to 
be executed (by posting an ECB upon which the main program is waiting, for 
example). 

Registers Upon Entry: When the TPEND exit-routine receives control, register 1 
contains the address of a two-word parameter list: 

• The first word contains the address of an ACB. This ACB is the ACB of the 
application program being shut down. 

• The value in the second word indicates the reason for the shutdown: 

The operator issued a HALT command, causing an ordinary closedown. 
4 The operator issued a HALT command, causing an quick closedown. 
8 VTAM is abnormally terminating. 

Other general purpose registers contain the following: 

Register 14: The address in VTAM to which the TPEND routine must branch 
when it is through processing. 

Register 15: The address of the TPEND routine. 

The contents of the remaining registers (0 and 2-13) are unpredictable. 

RELREQ=exit-routine address 

Indicates the address of a routine that is entered when another application program 
(or TOLTEP) requests connection to a terminal that is currently connected to your 
application program. This occurs when the other application program issues a 
SIMLOGON macro instruction (with the RELRQ and Q options specified) on 
behalf of your terminal. 

The RELREQ exit-routine may want to determine whether there are any I/O 
requests pending for the terminal and release it only after these I/O operations have 
been completed. If the application program wants to releasesthe terminal (this is 
optional), it should disconnect the terminal with a CLSDST macro instruction. This 
CLSDST macro instruction must have the RELEASE option code in effect for its 
RPL. The terminal is not disconnected until CLSDST is executed. 

If you have no RELREQ exit-routine, your application program cannot be notified 
at the other application program's request. If the request was issued with NQ set, 
the request is rejected. If Q was set, the request remains pending until you 
disconnect the terminal with CLSDST. 
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The application program that causes your RELREQ exit-routine to be invoked may 
have had the CONANY option code in effect for its SIMLOGON request. Although 
the use of CONANY causes VTAM to ultimately connect only one terminal, VTAM 
may in the process invoke many RELREQ routines. Thus you may release your 
terminal, only to have it remain unconnected when the other application program's 
request is satisfied by some other terminal. To prevent this problem, follow the 
CLSDST with an OPNDST (OPTCD= AC QUIRE) or SIMLOGON request of your 
own. Then if the other application program is ignoring your just-released terminal, 
you get it back. 

Registers Upon Entry: When the RELREQ exit-routine receives control, register 1 
contains the address of a two-word parameter list: 

• The first word of the parameter list contains the address of an ACB. This ACB is 
the ACB through which the terminal is currently connected to an application 
program. 

• The second word of the parameter list contains the address of the symbolic 
name of the requested terminal. 

The other registers contain the following: 

Register 14: The address in VTAM to which the RELREQ routine must branch 
when it is through processing. VTAM will handle the return of control to the 
instruction in the application program that was about to be executed when the 
RELREQ interruption occurred. 

Register 15: The address of the RELREQ routine. 

The contents of the remaining registers (0 and 2-13) are unpredictable. 

LOGON=exit-routine address 

Indicates the address of a routine to be entered when VTAM has queued a logon 
request for the application program. 

VTAM queues a logon request if (1) a terminal issues a logon request via the 
network solicitor, (2) the application program to which the terminal is currently 
connected issues a CLSDST macro instruction with OPTCD=PASS, (3) an 
application program issues a SIMLOGON macro instruction on behalf of the 
terminal, (4) the installation has specified automatic logon requests for the 
application program, or (5) the logical unit has issued an Initiate Self command. 
These cause the LOGON exit-routine to be scheduled if SETLOGON (OPTCD= 
START) is in effect. 

For automatic logon requests: If a BSC or start -stop terminal has been defined by 
the installation as a dial-in terminal (CALL=IN specified in the LINE or GROUP 
definition macro), the LOGON exit-routine is scheduled when the terminal 
operator dials in. If a BSC or start-stop terminal has been defined by the installation 
as a dial-out terminal (CALL=OUT), the LOGON exit-routine is scheduled when 
the application program opens its ACB and issues SETLOGON (OPTCD=START). 
(The terminal will not be dialed, however, until OPNDST is completed and the first 
I/O request is directed to it.) 

Regardless of the mechanism by which the LOGON exit-routine is scheduled, the 
routine is in effect being asked to connect the terminal to the application program. 
The routine's principal task therefore is to determine if it should honor the request, 
and when it determines that it should, issue an OPNDST macro instruction to 
establish connection with the terminal. If the request is not to be honored, the 
routine should issue the CLSDST macro instruction for the terminal (which 
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removes the terminal from the logon queue). If neither OPNDST nor CLSDST is 
issued, the terminal may remain unconnected to any application program. 

If MACRF=LOGON and SETLOGON (OPTCD=QUIESCE) has not been issued, 
logon requests are queued for your application program regardless of whether a 
LOGON exit-routinesis available. A logon request remains queued until you issue 
OPNDST or CLSDST for the terminal. 

Note that the "queuing" of a logon request does not necessarily mean that the 
request is queued for eventual scheduling of the LOGON exit list routine; it merely 
means that the request is queued for an eventual OPNDST (OPTCD=ACCEPT) 
macro instruction (or CLSDST). 

The LOGON exit-routine can issue an INQUIRE macro instruction to obtain the 
logon message supplied by the terminal making the logon request. If the routine 
determines from this logon message that connection should be requested, it may 
wish to establish that connection. This would be accomplished by using 
information passed to the LOGON exit-routine, along with information obtained 
with the INQUIRE macro instruction, to build or modify a NIB and an RPL, and 
by then issuing the OPNDST macro instruction with ACCEPT and SPEC option 
codes. 

The LOGON exit-routine is entered only if MACRF= LOGON was specified for the 
ACB, and the application program has issued the SETLOGON (OPTCD=START) 
macro instruction. 

Registers Upon Entry: When the LOGON exit-routine receives control, register 1 
contains the address of a 4-word parameter list: 

• The first word contains the address of an ACB. This ACB is the ACB to which 
the logon request was directed. The ACB address should be specified for the 
ACB operand of an INQUIRE macro instruction used to obtain the logon 
message. 

• The second word contains the address of the 8-byte symbolic name of the 
terminal requesting logon. This name should be placed in the NAME field of the 
NIB used to establish connection with the terminal. (The symbolic name being 
pointed to here is the same as the name of the terminal's entry in the resource 
definition table. The terminal's entry is either an LU, TERMINAL, or COMP 
entry, or, if the terminal is a dial-in terminal without an automatic ID 
verification feature, the UTERM name in a TERMINAL entry. TERMINAL and 
COMP are VTAM definition macros used by the installation to build entries in 
the resource definition table.) 

• The third word is reserved. 

• The fourth word contains the length of the logon message sent by the terminal. 
This length should be used with the LENGTH operand of any INQUIRE macro 
instruction used to obtain the logon message. 

Other registers contain the following: 

Register 14: The address in VTAM to which the LOGON exit-routine should 
branch when it is through processing. VTAM handles the return of control to the 
application program instruction that was about to be executed when the 
LOGON interruption occurred. 

Register 1 5 : The address of the LOGON exit-routine. 

The contents of the remaining registers (0 and 2-13) are unpredictable. 
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LOSTERM=exit-routine address 

Indicates the address of a routine to be entered when contact with a terminal has 
been lost. As noted below, the application program may or may not issue CLSDST 
to disconnect the terminal. 

If there is no LOSTERM exit-routine, the application program is not notified that 
contact has been lost, except via return codes following pending and subsequent 
I/O requests for the terminal. 

When the LOSTERM exit-routine is entered, the application program can no longer 
communicate with the terminal, although READ or RECEIVE macro instructions 
can still be issued to obtain data already sent from the terminal. The LOSTERM 
exit-routine may inform the main part of the application program that the terminal 
has been lost. 

Registers Upon Entry: When the LOSTERM exit-routine receives control, register 
1 contains the address of a 4-word parameter list. 

• The first word contains the address of an ACB. This ACB is the ACB of the 
application program to which the terminal was connected. 

• The second word contains the CID of the terminal. The ARG field of an RPL 
used for CLSDST must contain this CID. 

• The third word contains whatever had been placed in the USERFLD field of the 
NIB associated with the terminal. 

• The decimal value contained in the fourth word indicates why the LOSTERM 
exit-routine was entered: 

A dial-line disconnection occurred for a dial-in BSC or start-stop 

terminal. A CLSDST macro instruction is required. 

4 A dial-line disconnection occurred for a dial-out BSC or start-stop 

terminal, If no data from the terminal remains in VTAM buffers, a 
READ or WRITE (OPTCD=SPEC) macro instruction will redial the 
terminal. If redialing fails (causing the LOSTERM exit-routine to be 
rescheduled) the CLSDST macro instruction should be issued for the 
terminal. 

8 Reserved. 

12 Contact with a BSC terminal, start-stop terminal, or logical unit has 

been lost for one of the following reasons: (1) the network operator has 
issued a VARY command for the terminal, (2) the communication 
controller's NCP has begun an automatic network shutdown or has 
abended and cannot be restarted, (3) there has been a permanent 
channel failure between the CPU and the communication controller or 
locally attached terminal, (4) there has been a failure in the network 
path between the communication controller and the remotely attached 
terminal, or (5) a Test Request Message has been received from the 
terminal. A CLSDST macro instruction should be issued. 

16 When a logical unit is about to be restarted, VTAM first schedules the 

LOSTERM exit-routine with a decimal code of 24 in the parameter list. 
If the logical unit is successfully restarted, the LOSTERM exit-routine 
is rescheduled with this code (16) in the parameter list. An OPNDST 
macro instruction should be issued. 

20 An unconditional Terminate Self command has been issued by the 

logical unit. A CLSDST macro instruction is required. 

24 The logical unit is about to be restarted. If the logical unit is 

successfully restarted, VTAM reschedules the LOSTERM exit-routine 

39 



EXLST 



with a decimal code of 16 in the parameter list. If the logical unit is not 
successfully restarted, VTAM reschedules the exit-routine with a 
decimal code of 12 in the parameter list. Issue a CLSDST macro 
instruction for the logical unit. If you intend to resume communication 
if the logical unit is successfully restarted, you can issue RECEIVE 
macros (OPTCD=NQ) to obtain any data still in the network. (If data is 
still in the network when the logical unit is restarted, the data is 
discarded.) These RECEIVES must be issued before the CLSDST is 
issued. 

Other general purpose registers contain the following: 

Register 14: The address in VTAM to which the LOSTERM routine must 
branch when it is through processing. VTAM handles the return of control to the 
point in the application program where the LOSTERM interruption occurred. 

Register 15: The address of the LOSTERM exit-routine. 

The contents of the remaining registers (0 and 2-13) are unpredictable. 

ATTN=exit-routine address (Basic-mode only) 

Indicates the address of a routine to be entered when a start-stop terminal 
connected to the application program causes an attention interruption and no read 
or write operation is pending or in progress for the the terminal. 

Such an attention interruption causes an error lock to be set for the terminal by the 
CPU or the communication controller; no I/O can be performed with the terminal 
until this error lock is reset with a RESET macro instruction. 

If there is no ATTN routine to be invoked, the attention interruption is ignored and 
the error lock is automatically reset. 

The ATTN exit is taken only if (1) the application program specified PROC= 
MONITOR in the NIB representing the terminal that issued the attention 
interruption, and (2) the terminal is a 2741, 1050, Communicating Magnetic Card 
Selectric Typewriter, or an ATT Teletypewriter Terminal. 

The application program is notified of attention interruptions that occur during an 
I/O operation by means of a return code set in the FDBK2 field of the I/O request's 
RPL. 

Registers Upon Entry: When the ATTN routine receives control, register 1 contains 
the address of a 3-word parameter list: 

• The first word contains the address of an ACB. This ACB is the ACB through 
which the terminal issuing the attention interruption is currently connected. 

• The second word contains the CID of the terminal. The ARG field of any RPL 
used to communicate with this terminal must contain this CID. 

• The third word contains whatever had been placed in the USERFLD field of the 
NIB associated with the terminal. 

Other general purpose registers contain the following: 

Register 14: The address in VTAM to which the ATTN routine should branch 
when it is through processing. VTAM handles the return of control to the 
application at the point that the interruption for the ATTN exit occurred. 

Register 15: The address of the ATTN exit routine. 

The contents of the remaining registers (0 and 2-13) are unpredictable. 
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Registers Upon Entry: When the SCIP exit routine receives control, the register 
contents are the same as those described above for the DFASY exit routine. That 
is: 

Register 1 : The address of a parameter list containing the ACB address, the 
logical unit's CID and USERFLD data, and the address of the read-only RPL. 
The parameter list is summarized in Figure 3. 

Register 14: The address in VTAM to which the SCIP exit routine must return. 

Register 15: The address of the SCIP exit routine. 

The contents of the remaining registers (0 and 2-13) are unpredictable. 

TPEND=exit routine address 

Indicates the address of a routine to be entered when the network operator issues a 
HALT command, when VTAM detects an internal problem that necessitates halting 
itself, or when VTAM abnormally terminates. 

If the network operator issues a HALT command to close the network normally, 
I/O or connection requests that are being processed are completed before 
closedown. Pending connection requests cause the LOGON exit routine, if 
available, to be scheduled; attempts to accept the connection, however, will fail. 
Therefore, the LOGON exit routine should be notified that the TPEND exit routine 
has been entered. The LOGON exit routine can thus avoid unnecessary processing 
of connection requests. New requests are not permitted. The TPEND exit routine, 
in response to a normal HALT command, should issue an asynchronous CLSDST 
macro instruction for each connected terminal or cause the main program to issue a 
CLOSE macro instruction, which will result in the eventual disconnection of all the 
terminals. 

If the network operator issues a HALT command to close the network quickly or if 
VTAM detects an internal problem that necessitates halting itself, I/O or 
connection requests that are being processed are canceled, and the FDBK2 field of 
the RPL is set to indicate the reason for the cancelation. New requests are not 
permitted. SYNAD and LOSTERM exit routines, if available, are scheduled for any 
terminals that are connected at the time TPEND is entered. The TPEND exit 
routine, in response to a quick HALT command or VTAM halting itself, should not 
attempt to communicate with any of the connected terminals. It should issue an 
asynchronous CLSDST macro instruction for each connected terminal or cause the 
main program to issue a CLOSE macro instruction, which will result in the eventual 
disconnection of all the terminals. 

In OS/VS1 only, if the network operator issues a HALT command to cancel VTAM 
or if VTAM abnormally terminates, I/O and connection requests that are being 
processed are canceled. The FDBK2 field of the RPL is not set to indicate the 
reason for the cancelation. New requests are not permitted. SYNAD and 
LOSTERM exit routines are not scheduled. The TPEND exit routine, in response to 
a HALT command canceling VTAM or to VTAM abnormally terminating, should 
not attempt to communicate with any of the connected terminals. It should cause 
the main program to issue a CLOSE macro instruction, which will result in the 
disconnection of all the terminals at once; it may not issue CLSDST macro 
instructions. In DOS/VS and OS/VS2, the HALT command to cancel VTAM is not 
recognized, and VTAM abnormal termination is handled exactly as a quick HALT 
command. 

Note: A CLOSE macro instruction cannot be issued in an exit routine, but the 

TPEND exit routine can cause a CLOSE macro instruction to be issued in the main 

program (by posting an ECB upon which the main program is waiting, for 

example). 
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If there is no TPEND exit routine, the VTAM application program is not notified 
that a normal or quick HALT has been issued or that VTAM is halting itself except 
by means of the FDBK2 field of the RPL after a pending or new request has fatted. 
In addition, the application program is abnormally terminated when a HALT 
command canceling VTAM is issued or when VTAM abnormally terminates. In all 
of these situations, it is imperative that the terminals be disconnected. Failure to do 
so may result in the termination of the application program by the network 
operator. It is therefore strongly recommended that the application program 
include a TPEND exit routine. 

Registers Upon Entry: When the TPEND exit routine receives control, register 1 
contains the address of a 2-word parameter list (the parameter list is summarized in 
Figure 3): 

• The first word contains the address of an ACB. This ACB is the ACB of the 
application program being shut down. 

• The value in the second word indicates the reason for the shutdown: 

The network operator issued a HALT command to close the network 
normally. 

4 The network operator issued a HALT command to close the network 
quickly, or VTAM detected an internal problem and is halting itself. 

8 The network operator issued a HALT command to cancel VTAM or 
VTAM has abnormally terminated (OS/VS1 only). 

Other general purpose registers contain the following: 

Register 14: The address in VTAM to which the TPEND exit routine must 
branch when it is through processing. VTAM returns control to the instruction 
in the application program that was to be executed when the TPEND 
interruption occurred. 

Register 15: The address of the TPEND exit routine. 
The contents of the remaining registers (0 and 2-13) are unpredictable. 



RELREQ=exit routine address 

Indicates the address of a routine that is entered when another application program 
(or TOLTEP) requests connection to a terminal that is currently connected to your 
application program. This occurs when the other application program issues a 
SIMLOGON macro instruction (with the RELRQ and Q options specified) on 
behalf of your terminal. 

The RELREQ exit routine may want to determine whether there are any I/O 
requests pending for the terminal and release it only after these I/O operations have 
been completed. If the application program wants to release the terminal (this is 
optional), it should disconnect the terminal with a CLSDST macro instruction. This 
CLSDST macro instruction must have the RELEASE option code in effect for its 
RPL. The terminal is not disconnected until CLSDST is executed. When CLSDST is 
executed, the terminal is made available to the application program that has been 
waiting for it the longest amount of time. 

If you have no RELREQ exit routine, your application program cannot be notified 
at the other application program's request. If the request was issued with NQ set, 
the request is rejected. If Q was set, the request remains pending until you 
disconnect the terminal with CLSDST. 
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The application program that causes your RELREQ exit routine to be invoked may 
have had the CONANY option code in effect for its SIMLOGON request. Although 
the use of CONANY causes VTAM to ultimately connect only one terminal, VTAM 
may in the process invoke many RELREQ routines. Thus you may release your 
terminal, only to have it remain unconnected when the other application program's 
request is satisfied by some other terminal. To prevent this problem, follow the 
CLSDST with an OPNDST (OPTCD=ACQUIRE) or SIMLOGON request of your 
own. Then if the other application program is ignoring your just-released terminal, 
you get it back. 

Registers Upon Entry: When the RELREQ exit routine receives control, register 1 
contains the address of a 2-word parameter list (the parameter list is summarized in 
Figure 3): 

• The first word of the parameter list contains the address of an ACB. This ACB is 
the ACB through which the terminal is currently connected to an application 
program. 

• The second word of the parameter list contains the address of the symbolic 
name of the requested terminal. The name is 8 bytes long and padded on the 
right with blanks, if necessary. 

The other registers contain the following: 

Register 14: The address in VTAM to which the RELREQ routine must branch 
when it is through processing. VTAM will handle the return of control to the 
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GENCB— Generate a Control Block 



The GENCB macro instruction builds an ACB, EXLST, RPL, or NIB. The 
advantage of using the GENCB macro instruction is that the control blocks are 
generated during program execution. (With the ACB, EXLST, RPL, and NIB macro 
instructions, the control blocks are built during program assembly.) If GENCB, 
MODCB, TESTCB, and SHOWCB are used to build and manipulate the control 
blocks, program reassembly should not be required should control block formats be 
changed during future releases of VTAM. 

GENCB not only builds the control block during program execution, but can also 
build the control block in dynamically allocated storage. 

The GENCB user specifies the type of control block to be built and the contents of 
its fields. The operands used to specify the field contents are exactly the same as 
those used in the macro instruction that builds the control block. For example, 
these macro instructions build the same exit list: 

GENCB BLK=EXLST,SYNAD=SYNADPGM,AM=VTAM 

EXLST SYNAD=SYNADPGM,AM=VTAM 

The control block is built either in storage that VTAM obtains via the OS/VS 
GETMAIN or DOS/VS GETVIS facility, or in the application program's storage. To 
accomplish the latter, the application program should either reserve enough storage 
during program assembly to accomodate the control block, or perform its own 
GETMAIN or GETVIS operation to obtain the necessary storage. If the application 
program is providing the storage, the location and length of this storage must be 
coded in the GENCB macro instruction. Dynamic storage allocation for the control 
block occurs automatically if the location and length operands (WAREA and 
LENGTH) are omitted. The application program can issue FREEMAIN or 
FREEVIS macro instructions to free the storage obtained by GENCB. 

Dynamic storage allocation can be successful only if (1) the program is operating in 
virtual mode and (2) enough unallocated virtual storage remains in the program's 
partition or region to build the control block. See the description of the LENGTH 
operand for an explanation of how control block lengths are determined. 

List, generate, and execute forms of the GENCB macro instruction are available; 
they are designated by the MF operand. 

Because there is a large variety of formats in which the GENCB operands can be 
specified, format specifications have been tabulated in Appendix E and do not 
appear in this macro instruction description. 



Name 



Operation 



Operands 



[symbol] 



GENCB 



BLK={ ACB | EXLST | RPL | NIB } 

, keyword=value] ... 

,COPIES=quantity] 

, WAREA=work area address 

, LENGTH=work area length 
[ , MF=list, generate, or execute form parameters] 



BLK=ACB | EXLST I RPL | NIB 

Indicates the type of control block to be generated. 
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keyword=value 

Indicates a control block field and the value that is to be contained or represented 
within it. 

For keyword, code any keyword that can be used in the macro instruction 
corresponding to the BLK operand. If BLK=ACB is used, for example, code the 
keyword of any operand that can be used in the ACB macro instruction. One 
exception: ARG=(register) can also be coded if BLK=RPL. 

For value, indicate a register or code any value that could be used if the operand 
were being specified in the ACB, EXLST, RPL, or NIB macro instruction, or use 
one of the formats indicated in Appendix E. 

Note: // you are generating an ACB, RPL, or EXLST, AM=VTAM must be 
included. If no other keywords are included, the following types of control blocks 
are built: 

ACB: All fields are set to 0, and the MACRF field is set to NLOGON. 

RPL: All fields are set to their default values (as indicated in the RPL macro 
instruction description). 

EXLST: All exit-routine address fields are included and set to 0. 

NIB: All fields are set to their default values (as indicated in the NIB macro 
instruction description). 

COPIES=quantity 

Indicates the number of control blocks to be generated. 

The copies are identical in form and content. With the exception of an exit list, 
they are placed contiguously in storage, whether that storage is the area indicated 
by the WAREA operand or is dynamically allocated storage. Exit lists begin on the 
next fullword boundary following the end of the previous exit list. 

The length returned in register is the total length of the generated control blocks. 
The length of each block (the total length divided by the number of copies) can be 
used to determine the location of the beginning of each block. 

Note: If this operand is not used, one control block is built. 

WAREA=work area address 

Indicates the location of the storage area in the application program where the 
control block is to be built. The work area must be aligned on a fullword boundary. 
If this operand is specified, the LENGTH operand must also be specified. 

If the WAREA and LENGTH operands are omitted, VTAM obtains dynamically 
allocated storage via the GETMAIN or GETVIS facility and builds the control 
block there. Assuming that GENCB is completed successfully (this is indicated by a 
return code of in register 15), the address of the generated control block (or 
blocks) is placed in register 1, and their total length is placed in register 0. 

LENGTH=work area length 

Indicates the length (in bytes) of the storage area designated by the WAREA 
operand. 

If this length is insufficient, register 15 will contain the value 4, and register will 
contain the value 9. 
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To avoid having to recode your application program should you wish to run it 
under a different operating system, use the manipulative macro instructions to 
obtain the control block lengths. You do this by specifying ACBLEN, EXLLEN, 
RPLLEN, or NIBLEN in either a SHOWCB or TESTCB macro instruction. For 
example, to obtain the length of an ACB in your particular operating system, the 
following SHOWCB could be coded: 

SHOWCB FIELDS=ACBLEN,AREA=WORKAREA,LENGTH=4,AM=VTAM 

Or, to test the length of an exit list in your particular operating system, the 
following TESTCB could be coded: 

TESTCB EXLLEN=(7),AM=VTAM 

If you are generating more than one control block, remember that the total length 
of each control block is the length indicated by the control block's length field 
(ACBLEN, EXLLEN, RPLLEN, NIBLEN) plus the number of bytes required for 
fullword alignment. (EXLSTs are variable in length; when no specific EXLST is 
specified, the length returned by SHOWCB or tested by TESTCB is the maximum 
possible length for your operating system.) 

MF=list, generate, or execute form parameters 

Indicates that a list, generate, or execute form of GENCB is to be used. Omitting 
this operand causes the standard form of GENCB to be used. See Appendix F for a 
description of the nonstandard forms of GENCB. 

Examples GEN1 GENCB AM=VTAM,BLK=ACB 

APPLID=(3),EXLST=(6), 

WAREA=BLOKPOOL,LENGTH=(4) 



BLOKPOOL DS 3 2D 

GEN1 builds an ACB in statically reserved storage (BLOKPOOL). When GEN1 is 
executed, register 3 must contain the address of an application program's symbolic 
name, and register 6 must contain the address of the exit list to be pointed to by 
the ACB. 

L 10,WORKAREA (REG 10=ACB LENGTH) 

GETMAIN R,LV=(10) 

LR 5,1 (REG5=ACB ADDRESS) 

GEN2 GENCB AM=VTAM,BLK=ACB 

WAREA=(5),LENGTH=(10) 

In this example, the application program is building an ACB in dynamically 
allocated storage obtained by itself. Using the procedure described above in the 
LENGTH operand description, the application program has obtained the length of 
an ACB and placed it in a fullword called WORKAREA. The instructions preceding 
GEN2 obtain the correct amount of storage, and GEN2 builds the ACB in that 
storage. 

GEN3 GENCB BLK=RPL,COPIES=10,AM=VTAM 

GEN3 creates 10 RPLs in dynamically allocated storage obtained by VTAM. The 
address of the beginning of these RPLs is returned in register 1 , and the total length 
is returned in register 0. This length includes all padding for fullword alignment; the 
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RPLLEN field indicates the length of each unpadded RPL. Each RPL is built as 
though an RPL macro instruction with no operands had been issued. 

Return of Status Information After GENCB processing is finished and control is returned to the application 

program, register 15 indicates whether or not the operation was completed 
successfully. If the operation was completed successfully, register 15 is set to 0; if it 
was completed unsuccessfully, register 15 is set to either 4 or 8. If it is set to 8, 
register is also set indicating the specific nature of the error (see Appendix D). 
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INQUIRE— Obtain Terminal Information or Application Program Status 



There are seven types of INQUIRE. The setting of the RPL's option code 
determines which one is used. The following descriptions indicate the purpose and 
use of these options; see the operand descriptions for details regarding how each is 
specified. 

LOGONMSG 

INQUIRE obtains a logon message from a terminal that has requested logon for the 
application program. 

Note: A logon message cannot be obtained after OPNDST is issued. 

DEVCHAR 

INQUIRE obtains the device characteristics of a terminal, as they are defined by 
the installation in the resource definition table. These device characteristics can be 
used to define which processing options the program wants to be in effect for the 
NIB used to connect that terminal. This type of INQUIRE is also appropriate for 
use in LOGON exit-routines where the program is establishing connection with 
terminals whose identities are not known during program assembly. 

TERMS 

For a given LU, TERMINAL, LINE, CLUSTER, or GROUP entry in the resource 
definition table, INQUIRE builds a NIB or list of NIBs in the application program. 

The purpose of this type of INQUIRE is this: During VTAM definition, the 
installation can define a TERMINAL, LINE, GROUP, or CLUSTER entry and 
associate a set of terminals with that entry. If the application program builds one 
NIB that indicates this entry in its NAME field, it can then issue INQUIRE to 
generate NIBs for all of the terminals associated with the entry. Thus the 
application program need not be aware of the identities or the number of these 
terminals before establishing connection with them. This allows the installation, via 
the network operator or VTAM definition procedures, to vary the set of terminals 
after the application program has been assembled. 

COUNTS 

INQUIRE provides the number of terminals that are currently connected via a given 
ACB and the number of terminals that have requested logon via that ACB but have 
not yet been connected. 

APPSTAT 

INQUIRE checks a specified application program and determines whether the 
application program is accepting logon requests, never accepts logon requests, is 
temporarily not accepting logon requests, no longer accepts logon requests, or has 
not yet opened its ACB. A code representing each situation is returned in the RPL's 
FDBK field. 

CIDXLATE 

Given a terminal's CID, INQUIRE provides the symbolic name of that terminal. 
Conversely, given the symbolic name of a terminal, INQUIRE provides the 
corresponding CID of that terminal. 

When a terminal is connected to an application program, the symbolic name of that 
terminal is converted into a 4-byte equivalent called the CID. This CID must 
subsequently be used for all I/O requests for the terminal. 
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TOPLOGON 

When a terminal directs a logon request at an application program (ACB) or when a 
request is made on its behalf, the application program may or may not immediately 
satisfy that request. While the request remains unsatisfied, it is said to be queued to 
the ACB. If unsatisfied requests accumulate, more than one is queued to the ACB. 

The TOPLOGON option supplies the symbolic name of the terminal that is 
currently at the head of the queue for a given ACB. 

BSCID 

This version of INQUIRE is used when a terminal with an ID verification feature 
dials in and causes a logon request to be generated for the application program. If 
the application program determines that the terminal's name is one that was 
associated with an IDLST having NOMATCH=PASS in effect (see your system 
programmer) INQUIRE with OPTCD=BSCID supplies the terminal's ID verification 
sequence. 



Name 


Operation 


Operands 


[symbol] 


INQUIRE 


RPL=rpl address 

[ , rpl field name=new value] ... 



RPL=rpl address 

Indicates the location of the RPL that indicates which kind of processing INQUIRE 
is to perform. 

rpl field name=new value 

Indicates an RPL field to be modified, and the new value that is to be contained or 
represented within it. If you wish to avoid the possibility of program reassembly 
following future releases of VTAM, set the RPL field with MODCB macro 
instructions rather than with the INQUIRE macro instruction. 

Format: For rpl field name, code the keyword of the RPL macro instruction 
operand that corresponds to the RPL field being modified. The new value can be 
any value that is valid for that operand in the RPL macro instruction, or it can 
indicate a register. ARG=(register) can also be specified. 

Although any RPL operand can be specified, the following operands apply to the 
INQUIRE macro instruction: 

ACB=acb address 

Indicates the ACB that identifies the application program. 

ARG=(register) 

Indicates the register containing the CID of the terminal. Register notation must be 
used if the CID is to be placed in the ARG field with this INQUIRE macro 
instruction. This operand applies to the DEVCHAR and CIDXLATE forms of 
INQUIRE. 

NIB=nib address 

Indicates the NIB whose NAME field iden ifies the terminal or application program. 
This operand applies to the LOGONMSG, DEVCHAR, TERMS, APPSTAT, and 
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CIDXLATE forms of INQUIRE. For DEVCHAR and CIDXLATE, NIB=address 

and ARG=(register) are mutually exclusive methods of identifying the terminal. 

AREA=address of data area 

Indicates where the information produced by INQUIRE is to be placed. 

AREALEN=length of data area 

Indicates the maximum number of bytes of data that the data area can hold; if the 
data to be placed there exceeds this value, a special condition results (RTNCD=0, 
FDBK2=5). 

ECB | EXIT=ecb or rpl exit routine address 

Indicates the action to be taken by VTAM when an asynchronous (OPTCD=ASY) 
INQUIRE macro instruction is completed. The macro instruction is completed 
when the information has been placed in the application program's storage area. If 
EXIT is specified, the RPL exit-routine is scheduled. Otherwise the ECB is posted, 
and CHECK or WAIT must be used to determine when the posting occurs. See the 
RPL macro instruction for more information. 

OPTCD=SYN | ASY 

When the SYN option code is set, control is returned to the application program 
when the INQUIRE macro instruction has been completed. When ASY is set, 
control is returned as soon as VTAM has accepted the request. Once the INQUIRE 
operation has been completed, the ECB is posted or the RPL exit-routine is 
scheduled, depending on the setting of the ECB-EXIT field. 

OPTCD=LOGONMSG | DEVCHAR | COUNTS | TERMS | APPSTAT | CIDXLATE | 
TOPLOGONIBCSID 

LOGONMSG 

INQUIRE obtains a logon message from a terminal that has requested logon for the 

application program. 

The RPL's ACB field must indicate the ACB to which the logon request is directed. 
The NIB field must point to a NIB whose NAME field contains the symbolic name 
of the terminal issuing the logon request. The AREA and AREALEN fields must 
indicate the location and length of the storage area where the logon message is to be 
placed. 

Note: The information required for the ACB, NAME, and AREALEN fields is 
passed to the LOGON exit-routine in a parameter list. 

VTAM indicates the length of the logon message in the RPL's RECLEN field. If the 

message is too long to fit, RECLEN is posted with the required length. Conditional 
completion is indicated (RTNCD=0 and FDBK2=5), and no data is supplied to the 

application program. 

DEVCHAR 

INQUIRE obtains the device characteristics of a terminal, as they are defined by 
the installation in the resource definition table. 

The RPL must indicate the terminal in one of two ways: either the RPL's NIB field 
must indicate a NIB containing the symbolic name of the terminal, or the RPL's 
ARG field must contain the CID of the terminal. 
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The device characteristics are placed in an 8-byte program storage area whose 
location is set in the AREA field. The AREALEN field must be set to 8. The bits 
that are set in this area indicate whether the device is an input, output, or 
input/output device. The specific device type (for example, 3270 display station) is 
also indicated, along with additional information. See Appendix H for a complete 
description of the DEVCHAR information. 

TERMS 

For a given TERMINAL, LINE, CLUSTER, or GROUP entry in the resource 
definition table, INQUIRE builds a NIB or list of NIBs in the application program. 

The RPL's NIB field must point to a NIB whose NAME field contains the name of 
an entry that exists in the resource definition table at the time INQUIRE is 
executed. A NIB is built for each terminal represented in the entry. 

The AREA and AREALEN fields designate the location and length of the work 
area where the NIBs are built. The work area must be set to by the application 
program before INQUIRE is issued. 

VTAM indicates the total length of the NIBs in the RPL's RECLEN field. 

If the application program wants the NIBs to be built in dynamically allocated 
storage (obtained by the application program), INQUIRE should be issued twice. 
For the first INQUIRE, set AREALEN to 0. This INQUIRE will complete with 
RTNCD=0 and FDBK2=5 (insufficient length) and RECLEN will indicate the 
required length. Obtain the storage and issue INQUIRE with AREALEN set to the 
proper length. 

Each NIB contains the symbolic name of the terminal, with flags for the LISTEND 
field set in such a way as to group the NIBs together into a NIB list. In addition, 
device characteristics are placed in each NIB. These characteristics can be used to 
reset the PROC options of the NIB to values that are appropriate for the terminal. 

After the user has set each NIB's MODE field to BASIC or RECORD and other NIB 
fields to their desired values, the NIBs are ready to be used for connection. 

COUNTS 

INQUIRE provides the number of terminals that are currently connected via a given 
ACB and the number of terminals that have requested logon via that ACB but have 
not yet been connected. 

The RPL's ACB field must contain the address of the ACB. The AREA field must 
indicate a 4-byte area where the information is to be placed. VTAM places the 
number of connected terminals in the first 2 bytes and the number of terminals 
requesting logon in the second 2 bytes. 

APPSTAT 

INQUIRE checks a given application program and returns one of the following 
decimal values in the RPL's FDBK field: 

ACTIVE: The application program is accepting logon requests (that is, 

the ACB is open, its MACRF field is set to LOGON, and SETLOGON 
START has been issued). 

4 INACTIVE: The application program ACB is not open. 
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8 NEVER ACCEPTS: The application program has indicated that it never 

accepts logon requests (that is, the ACB was opened with MACRF= 
NLOGON specified). 

12 TEMPORARILY NOT ACCEPTING: The application program has 

indicated that logon requests should not be directed toward it. The 
application program has issued SETLOGON (OPTCD=STOP) which 
implies that this condition is temporary, and that SETLOGON 
(OPTCD=START) will eventually be issued to indicate that logon 
requests can again be directed toward it. An INQUIRE issued after the 
application program issues SETLOGON (OPTCD=START) causes a 
FDBK code of to be returned. 

16 NO LONGER ACCEPTING: The application program has issued 

SETLOGON (OPTCD=QUIESCE) and logon requests cannot be 
directed toward it. Unlike a return code of 12, a return code of 16 
means that the application program's logon request queue is now 
permanently closed. Presumably, the application program is about to 
close its ACB. 

The RPL's ACB field must contain the address of an opened ACB. 

The RPL's NIB field must point to a NIB whose NAME field contains the symbolic 
name of the application. (Although the NIB is generally used as a terminal control 
block, note that here it is being used to identify an application program. The 
symbolic name in the eight-byte NAME field must be left-justified and padded to 
the right with blanks. (This name corresponds to the application program's APPL 
entry in the resource definition table.) 

CIDXLATE 

Given a terminal's CID, INQUIRE provides the symbolic name of that terminal. 
Conversely, given the symbolic name of a terminal, INQUIRE provides the 
corresponding CID of that terminal. 

To convert that CID back into its equivalent symbolic name, the RPL's ARG field 
must contain the CID when the INQUIRE macro instruction is executed. The 
symbolic name is returned in the data area that you indicate in the RPL's AREA 
field. The AREALEN field must be set to 8. 

To use INQUIRE to convert the symbolic name into a CID, the RPL's NIB field 
must contain the address of a NIB. The NAME field of that NIB must in turn 
contain the symbolic name to be converted. The CID is placed in the data area that 
you indicate in the RPL's AREA field. The AREALEN field must be set to 4. 

Note: The NIB and the ARG field occupy the same physical field in the RPL. If 
the last macro instruction operand used to set or modify this field was 
ARG=(register), or if the field has been left unchanged since VTAM inserted a CID 
into it, VTAM recognizes that this field contains a CID. If the last operand used to 
set or modify this field was M5=address, VTAM recognizes that the field contains a 
NIB address. 

TOPLOGON 

INQUIRE returns the symbolic name of the terminal that has directed a logon 
request at the application program, and has spent the greatest amount of time 
waiting to be connected. If no logon requests are queued, an error return code 
results (see Appendix C). 
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The ACB field ,of INQUIRE's RPL must indicate the ACB whose logon request 
queue is to be examined. The symbolic name is returned in the data area indicated 
by you in the RPL's AREA field. The AREALEN field must be set to 8. 

BSCID 

INQUIRE returns the terminal's ID verification sequence. The RPL's NIB field 
must point to a NIB whose NAME field contains the symbolic name of the terminal 
(as provided in the LOGON exit-routine's parameter list). The sequence, which can 
be up to 20 bytes long, is placed in the storage area pointed to by the AREA field. 
Set the AREALEN field to 20. 



Examples 



INQ1 


INQUIRE 


RPL=RPL1 ,OPTCD=APPSTAT,NIB=NIBl 


TST1 


TESTCB 


RPL=RPL1,FDBK=0 




BE 


ACTIVE 



NIB1 



NIB 



NAME=PGM1 



INQ1 determines whether PGM1 is active and accepting logon requests. The answer 
is returned in RPLl's FDBK field. TST1 and the branch instruction cause a branch 
to ACTIVE if the application program is active and accepting logon requests. 



INQ2 



INQUIRE RPL=RPL2,OPTCD=LOGONMSG, 

ACB=ACB1,NIB=NIB2 

AREA=LGNMSG, AREALEN= 1 00 



NIB2 
LGNMSG 



NIB 
DS 



NAME=TERM2 
CL100 



Return of Status Information 



INQ2 obtains the logon message that was sent from the terminal whose symbolic 
name is contained in NIB2 and that was directed to the application program 
represented by ACB1 . This message is placed in the area designated as LGNMSG. 

When the INQUIRE operation is completed, the following RPL fields are set: 

If INQUIRE (OPTCD=APPSTAT) has been completed normally, as indicated in 
register 15, the FDBK field is set as shown above. 

If INQUIRE (all versions except OPTCD=APPSTAT) has been completed 
normally, the RECLEN field indicates the number of bytes of data that have 
been placed in the work area designated by the AREA field. If INQUIRE was 
completed successfully but the FDBK2 field indicates that the work area was 
too small (FDBK2=5), RECLEN indicates the required length. 

The value 26 (decimal) is set in the REG field indicating an INQUIRE request. 

The RTNCD and FDBK2 fields are set as indicated in Appendix C. 

Registers and 15 are also set as indicated in Appendix C. 
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INTRPRET— Interpret an Input Sequence 



INTRPRET allows each application program to use translation tables for each 
terminal that are specified by the installation and maintained by VTAM, rather 
than tables that are created and maintained by each application program. 

During VTAM definition, the installation identifies each terminal in its 
teleprocessing network, and optionally associates an interpret table with each one. 
The interpret table contains one or more variable-length sequences that the terminal 
is capable of sending— such as graphic characters, tab characters, or program 
function key characters. With each of these sequences, the installation specifies a 
corresponding 8-byte sequence (or the address of an installation-written routine 
that will generate an 8-byte sequence). An application program issuing INTRPRET 
identifies the terminal and provides a particular sequence received from the 
terminal; VTAM, if it finds that sequence in the interpret table for that terminal, 
returns the corresponding sequence to the application program. 

As an example, assume that the installation defines the following interpret tables 
for two terminals, T2741 and T3270: 



T2741 's interpret table 


T3270's interpret table 


_Logon. 

Repeat last xmission. 

Stop. 


LOGON 

REPEATLT 

STOP 


LGN 

# 
@ 


LOGON 

REPEATLT 

LIST 



If an application program receives the sequence "Repeat last xmission." from 
T2741 , INTRPRET (if provided with the sequence and the identity of the terminal) 
would return the sequence "REPEATLT" to the application program. If the 
application program identifies T3270 and provides the sequence " " to INTRPRET, 
INTRPRET would return the corresponding sequence— in this case, another 
"REPEATLT"-to the application program. 



Name 


Operation 


Operands 


[symbol] 


INTRPRET 


RPL=rpl address 

[ , rpl field name=new value] ... 



RPL=rpl address 

Indicates the location of the RPL from which INTRPRET obtains needed 
information from the application program, and into which it returns completion 
status information. 

rpl field name=new value 

Indicates an RPL field to be modified and the new value that is to be contained or 
represented within it. If you wish to avoid the possibility of program reassembly 
following future releases of VTAM, set the RPL field with MODCB macro 
instructions rather than with the INTRPRET macro instruction. 
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Format: For rpl field name code the keyword of the RPL macro instruction 
operand that corresponds to the RPL field being modified. The new value can be 
any value that is valid for that operand in the RPL macro instruction or it can 
indicate a register. ARG=(register) can also be coded. 

Although any RPL operand can be specified, the following operands apply to an 
INTRPRET macro instruction: 

ACB=acb address 

Indicates the ACB that identifies the application program. 

ARG=(register) 

Indicates the register containing the CID of the terminal. VTAM looks for an 
interpret table for this terminal. 

NIB=nib address 

Indicates the NIB whose NAME field identifies the terminal. VTAM looks for an 
interpret table for this terminal. If the NIB field does not indicate a NIB address, 
the ARG field must contain a CID. 

AREA=data address 

Indicates the data area containing the sequence being submitted to VTAM for 
interpretation. 

RECLEN=data length 

Indicates how many bytes are being submitted to VTAM for interpretation. 

AAREA=data area address 

Indicates the data area where VTAM is to place the interpreted sequence. 

AAREALN=data area length 

Indicates the capacity of the data area where VTAM is to place the interpreted 
sequence. This value should be at least 8. 

ECB | EXIT=ecb or rpl exit-routine address 

Indicates the action to be taken by VTAM when an asynchronous (OPTCD=ASY) 
INTRPRET macro instruction is completed. If EXIT is specified, the RPL 
exit-routine is scheduled. Otherwise the ECB is posted, and CHECK or WAIT must 
be used to determine when the posting occurs. See the RPL macro instruction for 
more information. 

OPTCD=SYN|ASY 

When the SYN option code is set, control is returned to the application program 
when the INTRPRET macro instruction has been completed. The macro instruc- 
tion is completed as soon as the data has been placed in the application program's 
storage area. When ASY is set, control is returned as soon as VTAM has accepted 
the request. Once the INTRPRET macro instruction has been completed, the ECB 
is posted or the RPL exit-routine is scheduled, depending on the setting of the ECB- 
EXIT field. 
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Example 



INT1 INTRPRET RPL=RPL1, 

NIB=NIB6,AREA=INSEQ,RECLEN=(3), 

AAREA=0UTSEQ,AAREALN=8 



RPL1 


RPL 




INSEQ 


DS 


CL180 


NIB6 


NIB 


NAME=TERM1 


OUTSEQ 


DS 


CL8 



An application program has read a block of data from TERM1 and issues INT1 to 
interpret that data. NIB6 identifies the terminal, hence the interpret table to be 
used, AREA indicates the data area containing the data to be interpreted (INSEQ), 
and RECLEN indicates the amount of data to be interpreted. Note that if 
INTRPRET uses the same RPL that was used to read the data, the NIB-ARG field, 
the AREA field, and the RECLEN field would already be correctly set. 

Upon completion of INT1, the corresponding sequence is placed in the data area 
identified by the AAREA field (OUTSEQ). Although two separate data areas have 
been provided in this example for the "input" data (INSEQ) and the "output" data 
(OUTSEQ), there is no reason why the same data area could not be used. 



Return of Status Information 



When the INTRPRET operation is completed, these RPL fields are set: 

If the FDBK2 field indicates that INTRPRET failed because the data to be 
placed in the AAREA work area would not fit (FDBK2=5), the ARECLEN field 
contains the number of bytes required to hold the data. If INTRPRET was 
completed successfully, the ARECLEN field indicates how many bytes of data 
have actually been placed in the AAREA work area. 

The value 27 (decimal) is set in the REQ field, indicating an INTRPRET request. 



The. RTNCD and FDBK2 fields are set as indicated in Appendix C. Errors 
described in Appendix C include: 

• There is no such terminal (invalid NIB or CID). 

• There is no interpret table defined for the terminal. 

• The input area is too small. 

• There is no such sequence in the interpret table. 

• The sequence in the interpret table was found, but the routine that is 
supposed to generate a corresponding sequence has not been loaded. 

Registers and 15 are also set as indicated in Appendix C. 
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LDO— Create a Logical Device Order (Basic-mode only) 



With the READ, WRITE, SOLICIT, and RESET macro instructions, the application 
program can perform all but a few of the I/O operations provided by VTAM. To 
request any of the following I/O operations, however, the application program must 
use the DO and LDO macro instructions: 

• Copy the contents of a remotely attached 3277 Display Station buffer to the 
buffer of any printer or display unit attached via the same control unit. Use the 
COPYLBM or COPYLBT LDOs. 

• Read the entire contents of a 3270 display unit's buffer. (To simply read the 
data that the terminal operator sends, use the READ macro instruction.) Use the 
READBUF LDO. 

• Send a positive or negative acknowledgment accompanied by leading graphic 
characters, to a System/3 or System/370 CPU, and then read a block of data 
from it. Use the WRTPRLG or WRTNRLG LDOs. 

• Write data beginning with a block of heading characters to a System/3 or 
System/370 CPU. Use the WRTHDR LDO. 

• End an NCP session with a terminal. Use the DISCONCT LDO. 

• Erase the entire display screen of a 3270 display station (or a 2265 display 
station attached to a 2770 Data Communication System) and write a block of 
data, or erase only the unprotected portion of a 3270 display station screen and 
write no data. Although these operations are available through the WRITE 
macro instruction, the latter does not allow erasure to be combined with a 
conversational WRITE operation. If the ERASELBM or ERASELBT LDOs are 
followed by a chained READ LDO, however, a combined erase-write-read 
operation can be achieved. If the EAU LDO is followed by a chained READ 
LDO, a combined erase-read operation can be achieved. 

The LDO macro instruction generates a control block during program assembly that 
indicates one of the above I/O operations. The actual operation is performed when 
a DO macro instruction is executed. 

Some LDOs can be combined to form a series of operations, much like channel 
command words can be combined to form a channel program. 

An LDO has four parts: 



A 


B 


C 


D 




1 byte 




- 2 bytes 






1 byte 






*t oyies 





A command indicator. This indicates the specific I/O operation to be performed. 

A chaining indicator. A flag can be set in some of the LDOs that cause DO 
processing to also use the next contiguous LDO in storage. 

A length indicator. This indicates the length of the data or data area. (The RPL also 
has corresponding data address and length fields, but these indicate the LDO address, 
not the data address, when the RPL is used by DO.) 

A data address or a data area address. Depending on the command, this address 
indicates an area containing data, or a storage area where data is to be placed. 
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Although the operands corresponding to these parts are optional when the LDO 
macro instruction is coded, the command, and usually the data address and length 
indicator must be set before the DO macro instruction is executed. The LDO 
command descriptions below indicates whether these fields must be set. Assembler 
language must be used if you want to set LDO fields during program execution. 
You cannot use the manipulative macro instructions to modify LDO fields. 



Name 


Operation 


Operands 


[symbol] 


LDO 


[ CMD=command ] 

[, ADDR=data address or data area address] 

[ , LEN=data length or data area length] 

[,FLAGS=C|D] 



CMD=command 

Format: After the CMD keyword, code any of the following values: 

COPYLBM WRITE WRTNRLG EAU 

COPYLBT WRITELBM WRTPRLG DISCONCT 

READ WRITELBT ERASELBM 

READBUF WRTHDR ERASELBT 

Function: Indicates the specific I/O operation to be performed. 

COPYLBM 

This LDO causes the entire contents of a 3277 Display Station buffer to be copied 
to a printer or another display unit in the same remotely attached information 
display system. VTAM sends the copy request as a message by adding an ETX line 
control character at the end. This LDO applies only to remotely attached 3270 
terminals. 

The ADDR and LEN operands of this LDO must indicate the location and length of 
a data area containing (1) a 3270 copy control character and (2) the rightmost 2 
bytes of the "from" device's CID. For an explanation of the copy control 
character, refer to IBM 3270 Information Display System Component Description, 

G All -21 49. 

The ARG field of the DO macro instruction's RPL must contain the CID of the 
"to" device. 

COPYLBT 

The COPYLBT LDO performs like the COPYLBM LDO, except that after the data 
has been copied, VTAM waits for the receiving device's acknowledgment, and sends 
an EOT character after the acknowledgment is received. (The LBM and LBT in the 
COPYLBM and COPYLBT LDOs stand respectively for "last block in message" and 
"last block in transmission.") 

READ 

The READ LDO obtains a block of data from a System/3 or System/370 CPU and 
places it in a storage area in the application program. 



The READ LDO causes VTAM to perform the same action that a READ macro 
instruction does. However, a READ LDO can be command-chained after a 
WRTPRLG or WRTNRLG LDO. This allows the application program to either (1) 
send a negative acknowledgment to the device and then reread the data sent by it or 
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(2) send a positive acknowledgment to the device and then read the next block of 
data (or EOT character) sent by it. By generating its own responses in this manner, 
the application program can send leading graphic characters along with the 
response. 

If, at the time DO is executed, no solicited data is in VTAM buffers from the 
terminal, VTAM first solicits data from the terminal. This "implicit" solicitation 
operates as if a SOLICIT macro instruction had been issued. 

The ARG field of the DO macro instruction's RPL must contain the CID of the 
device. The ADDR and LEN fields of the READ LDO must indicate the location 
and length of the storage area where the data is to be placed. 

If the data to be placed there is too long to fit, and the TRUNC option code is in 
effect, the excess data is discarded. If the KEEP option is in effect instead of 
TRUNC, as much data as will fit is placed in the input area, and the length of the 
moved data is placed in RECLEN (so RECLEN=LEN), and the LDO's address is 
placed in the RPL's AAREA field. The excess data can be obtained with another 
READ LDO or with a READ macro instruction. 

READBUF 

The READBUF (read buffer) LDO causes the entire contents of a 3275 or 3277 
Display Station's buffer to be placed in an area in the application program. VTAM 
sends the device-control characters required to distinguish this kind of input 
operation from a normal read operation (which obtains data only when the 
terminal operator enters data and presses ENTER). This LDO applies to both 
locally and remotely attached 3270 terminals. 

The ARG field of the DO macro instruction's RPL must contain the CID of the 
sending device. 

The ADDR and LEN operands of this LDO indicate the address and length of the 
storage area where the data is to be placed. The action taken when the data is too 
long to fit is the same as described above for READ. 

WRITE 

The WRITE LDO writes a block of data to a System/3 or System/370 CPU. For 
these devices, the WRITE LDO works exactly like a WRITE macro instruction with 
a BLK option code; an STX character is added to the beginning of the data, and an 
ETB line control character is added to the end. However, if a WRITE LDO is 
command-chained after WRTHDR LDO, (by specifying FLAGS=C on the 
WRTHDR LDO), this sequence is written: 

S S E 

heading T text T 
H X B 

The ADDR and LEN operands of the WRITE LDO must indicate the location and 
length of the text data to be written. The ARG field of the DO macro instruction's 
RPL must contain the CID of the receiving device. 

WRITELBM 

The WRITELBM LDO writes a block of data to a System/3 or System/370 CPU. 
For these devices, WRITELBM works exactly like a WRITE macro instruction with 
an LBM option code; an STX character is added to the beginning of the data, and 
an ETX character is added to the end. However, if a WRITELBM LDO is chained 
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after a WRTHDR LDO, this sequence is written: 

S S E 

heading T text T 
H XX 

The ADDR and LEN operands of the WRITELBM LDO must indicate the location 
and length of the text to be written. The ARG field of the DO macro instruction's 
RPL must contain the CID of the receiving device. 

WRITELBT 

The WRITELBT writes a block of data to a System/3 or System/370 CPU. For 
these devices, WRITELBT works exactly like a WRITE macro instruction with an 
LBT option code; the data is preceded with an STX character and followed with an 
ETX character, and when an acknowledgment is received from the device, an EOT 
character is sent. However, if a WRITELBT LDO is chained after a WRTHDR LDO, 
this sequence is written: 

S S E E 

O heading T text T | 
H X X J T 

acknowledgment 
received — — *' 

The ADDR and LEN operands of the WRITELBT LDO must indicate the location 
and length of the text to be written. The ARG field of the DO macro instruction's 
RPL must contain the CID of the receiving device. 

WRTHDR 

The WRTHDR LDO writes a block of heading characters to a System/3 or 
System/370 CPU. The heading characters are provided by the user; VTAM inserts 
an SOH character at the beginning of the block and an ETB character at the end. 

If a WRITE, WRITELBM, or WRITELBT LDO is chained to a WRTHDR LDO (by 
specifying FLAGS=C on the WRTHDR LDO), the ETB character is not inserted 
after the heading. See the above descriptions of the WRITE, WRITELBM, and 
WRITELBT commands. 

The ADDR and LEN operands of this LDO must indicate the location and length of 
the heading characters to be written. The ARG field of the RPL being used by the 
DO macro instruction must contain the CID of the receiving device. 

WRTNRLG 

The WRTNRLG LDO (write negative response with leading graphics) sends a NAK 
character, accompanied by up to seven leading graphic characters, to a System/3 or 
System/370 CPU. WRTNRLG can be used only if it is command-chained before a 
READ LDO (by specifying FLAGS=C on the WRTNRLG LDO) and if BLOCK has 
been specified for the device's NIB. 

The ADDR and LEN operands of the WRTNRLG LDO must indicate the location 
and number of graphic characters to be used. The ARG field of the DO macro 
instruction's RPL must contain the CID of the receiving device. 

WRTPRLG 

The WRTPRLG LDO (write positive response with leading graphics) sends an ACKO 
or ACK1 sequence, accompanied by up to seven leading graphic characters, to a 
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System/3 or System/370 CPU. WRTPRLG can be used only if it is command- 
chained before a READ LDO (by specifying FLAGS=C on the WRTPRLG LDO) 
and BLOCK has been specified for the device's NIB. 

The ADDR and LEN operands of the WRTPRLG LDO must indicate the location 
and number of graphic characters to be used. The ARG field of the DO macro 
instruction's RPLmust contain the CID of the receiving device. 

ERASELBM 

The ERASELBM LDO (erase, write last block of message) erases the screen of a 
3270 display station or the screen of a 2265 display station attached to a 2770 
Data Communication System. It then writes a block of data ending with STX to the 
terminal. A READ LDO can be chained after an ERASELBM LDO. 

The ADDR and LEN operands of the ERASELBM LDO must indicate the location 
and length of the data to be written. The ARG field of the DO macro instruction's 
RPL must contain the CID of the terminal. 

ERASELBT 

The ERASELBT LDO (erase, write last block of transmission) works exactly like 
the ERASELBM LDO, except that after the data is sent to the terminal and an 
acknowledgement is received, an EOT character is sent. A READ LDO can be 
chained after an ERASELBT LDO. 

EAU 

The EAU LDO (erase all unprotected) erases the unprotected portion of a 3270 
display station's screen. No data is written to the terminal. A READ LDO can be 
chained after an EAU LDO. 

The ARG field of the DO macro instruction's RPL must contain the CID of the 
terminal. 

DISCONCT 

The DISCONCT (disconnect) LDO sends an EOT to the terminal and terminates 
the NCP session with the terminal. The ARG field of the DO macro instruction's 
RPL must contain the CID of the terminal. 

ADDR=data address or data area address 

Indicates the location of the data or data area to be used when the LDO is 
processed. 

For COPYLBM and COPYLBT LDOs, ADDR points to a 3270 copy control 
character and rightmost 2 bytes of the "from" device's CID. For the READ and 
READBUF LDOs, ADDR indicates where the data obtained by these LDOs is to be 
placed. For the output LDOs, ADDR indicates the location of the data that is to be 
written to a device. 

If you omit this operand, the ADDR field is set to 0. Register notation is not 
permitted. 

LEN=data length or data area length 

Indicates the length (in bytes) of the data or data area specified in ADDR. 

For COPYLBM and COPYLBT LDOs, this value should always be set to 3. For 
READ and READBUF LDOs, VTAM uses this value to determine whether the data 
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to be placed there is too big to fit. For all output LDOs, LEN indicates how many 
bytes of data are to be written. 

The maximum length you can specify is 32,767 bytes. If you omit this operand, the 
LEN field is set to 0. 



Examples 



Register notation is not permitted. 

FLAGS=C | D 

Indicates the action that the DO macro instruction is to take after it has used this 
LDO. The presence of this operand indicates that DO is to continue with the next 
contiguous LDO in storage. FLAGS=C (command chaining) indicates that the 
entire LDO is to be used. FLAGS=D (data chaining) indicates that only the ADDR 
and LEN fields of the next LDO are to be used. The absence of this operand 
indicates to DO that no further LDOs are to be used. 

The following example illustrates the use of the COPYLBM LDO. 

PRIME SHOWCB NIB=NIB1,AREA=TEMP,LENGTH=4,FIELDS=CID 

MVC CPYSCRNl+l(2),TEMP+2 

L 6,TEMP 

CPYSCRN DO RPL=RPL1 5 ARG=(6),AREA=LD01 



LDOl LDO 

TEMP DS 

CPYSCRN1 DC 



CMD=COPYLBM,ADDR=CPYSCRNl ,LEN=3 
F (TEMP=WORK AREA FOR CID) 

X'630000' (63=A COPY CONTROL CHARACTER, 

0000=FINAL AREA FOR RIGHT 

HALF OF CID) 



The purpose of the three instructions at PRIME is to obtain the CID of a device 
(from NIB1 into TEMP) and place the rightmost 2 bytes of the CID into a data area 
pointed to by LDOl . When CPYSCRN is executed, the device whose CID has be 
placed in register 6 will be the recipient of the copy operation. 

The next example shows how a READBUF LDO might be used. 
READ2 DO RPL=RPL2,ARG=(7),AREA=READLDO 



READLDO LDO CMD=READBUF,ADDR=WORKAREA,LEN=480 

WORKAREA DS CL480 

When READ2 is executed, register 7 must contain the CID of a 3270 display unit. 
VTAM will obtain the entire contents of that device's buffer and place it in 
WORKAREA. 

The following example illustrates the use of the WRTHDR LDO. 
WRITEIT DO RPL=RPL3,ARG=(8),AREA=HDRLDO 



HDRLDO 


LDO 


TXTLDO 


LDO 


HDRBLOK 


DS 


TXTBLOK 


DS 



CMD=WRTHDR,ADDR=HDRBLOK,LEN=5,FLAGS=C 

CMD=WRITE,ADDR=TXTBLOK,LEN=l 6 

CL5 

CL200 
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When WRITEIT is executed, VTAM sends a heading block from AHDRBLOK 
combined with a text block from ATXTBLOK. The line control characters added 
by VTAM make the sequence look like this: 



S data 


S data 


E 


from 


T from 


T 


H AHDRBLOK 


X ATXTBLOK 


B 



The following example shows how a WRTPRLG LDO can be command-chained to 
a READ LDO. 



POSRSP 



DO RPL=RPL4,ARG=(9),AREA=RSPLDO 



RSPLDO LDO CMD=WRTPRLG,ADDR=GRAPHICS,LEN=7,FLAGS=C 

THENREAD LDO CMD=READ,ADDR=INAREA,LEN=480 
GRAPHICS DC CCPU3003' 

When POSRSP is executed, register 9 must contain the CID of a device. VTAM 
sends a positive response (ACKO or ACK1) to the device, accompanied by seven 
leading graphic characters from GRAPHICS. The next LDO causes VTAM to read 
the next block of data from the device. 
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MODCB— Modify the Contents of Control Block Fields 



MODCB modifies the contents of one or more fields in an ACB, EXLST, RPL, or 
NIB control block. MODCB works with control blocks created either with 
declarative macro instructions or with the GENCB macro instruction. 

The user of the MODCB macro instruction indicates the location of an ACB, 
EXLST, RPL, or NIB, the fields within that control block to be modified, and the 
new values that are to be placed or represented in these fields. 

Any field whose contents can be set with the ACB, EXLST, RPL, or NIB macro 
instruction can be modified by the MODCB macro instruction. The operands used 
to do this are the same as those used when the control block is created. 

The following restrictions apply to the use of MODCB: 

• An ACB cannot be modified after an OPEN macro has been issued for it. 

• An exit list (EXLST) cannot have exits added to it with the MODCB macro 
instruction. If an exit list field is not specified in the EXLST macro instruction, 
do not attempt to modify that field with a MODCB macro instruction. MODCB 
can, however, be used to change dummy exit addresses to valid addresses. 

• An RPL cannot be modified while a request using that RPL is pending, that is, 
while the RPL is active. 

• A NIB should not be modified while its address is in the NIB field of an active 
RPL. 

• The AM field of the ACB, EXLST, and RPL control blocks cannot be modified. 
Once a control block has been generated in a VTAM-compatible form, it cannot 
later be modified for use with another access method. 

List, generate, and execute forms of the MODCB macro instruction are available; 
they are designated by the MF operand. 

Because there are a large variety of formats in which the various MODCB operand 
values can be specified, the operand format specifications have been tabulated in 
Appendix E, and do not appear here. 



Name 


Operation 


Operands 


[symbol] 


MODCB 


AM=VTAM 

( , ACB=acb address j 

) , EXLST=exit list address ( 

j , RPL=rpl address ( 

\ , NIB=nib address ) 

{, field name=new value }... 

[ , MF=list, generate, or execute form parameters] 



AM=VTAM 

Identifies this macro instruction as a VTAM macro instruction. This operand is 
required. 
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Example 



ACB=acb address 
EXLST=exit list address 
RPL=rpl address 
NIB=nib address 

Indicates the type and location of the control block whose fields are to be 
modified. 

field name=new value 

Indicates a field in the control block to be modified and the new value that is to be 
contained or represented within it. 

For field name, code the keyword of any operand that can be coded in the macro 
instruction corresponding to the ACB, EXLST, RPL, or NIB operand. If 
RPL=RPL1 is coded, for example, the keyword of any operand in the RPL macro 
instruction can be coded. ARG=(register) can also be coded. 

For new value, EXLST, RPL, or NIB macro instruction, or use one of the formats 
indicated in Appendix E. 

MF=list, generate, or execute form parameters 

Indicates that a list, generate, or execute form of MODCB is to be used. Omitting 
this operand causes the standard form of MODCB to be used. See Appendix F for a 
description of the nonstandard forms of MODCB. 

MODI MODCB RPL=(5),OPTCD=(ASY,SPEC,CS),AREA=(6),AM=VTAM 

MODI activates the ASY, SPEC, and CS option codes in an RPL. The settings for 
the other option codes are not affected. The address of this RPL must be in register 
5 when MODI is executed. 



Return of Status Information 



After MODCB processing is completed, register 15 indicates whether or not the 
operation completed successfully. If the operation completed successfully, register 
15 is set to 0; if it completed unsuccessfully, register 15 is set to either 4 or 8. If it 
is set to 4, register is also set indicating the specific nature of the error (see 
Appendix D). 
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NIB— Create a Node Initialization Block 



The NIB generated by the NIB macro instruction is used by the program to identify 
which terminal is to be connected when an OPNDST macro instruction is executed. 
It also indicates how VTAM is to handle subsequent communication between the 
program and that terminal. In this sense a NIB works like an RPL, in that both 
contain information that governs I/O requests. But the information in a NIB relates 
to the terminal the NIB represents and governs all communication directed at that 
terminal. (The RPL, in contrast, supplies additional information relating to the 
transaction itself, such as the location of data to be written to a terminal or 
whether or not the request is to be handled asynchronously.) 

When OPNDST is issued, the NIB field of its RPL points to a NIB. Once connection 
is established, VTAM associates the terminal with information contained in the 
NIB-information that is placed in the NIB by the USERFLD, MODE, and PROC 
operands of the NIB macro instruction. This association continues as long as the 
terminal remains connected even though the storage containing the NIB can be used 
for other purposes as soon as OPNDST is completed. If the USERFLD or PROC 
information is to be altered during that time (basic-mode only), the MODCB macro 
instruction or a new NIB must be used to make the appropriate changes in the 
USERFLD or PROC fields of a NIB (either the original or a new one), and the 
CHANGE macro instruction must be used to make these modifications effective. 

NIBs can be grouped together into lists. When OPNDST (OPTCD= ACQUIRE) and 
SIMLOGON requests are directed towards a NIB that is the first in a NIB list, 
VTAM considers all of the terminals represented in the NIB list to be the objects of 
the request, not just the terminal represented by the first NIB. 

A field called the CID field is part of every NIB. It is not represented in the NIB 
macro instruction because its contents cannot be set by the application program. 
When the terminal represented by the CID is connected to the program, VTAM 
generates an equivalent of the terminal's symbolic name and places it both in the 
NIB's CID field and in the ARG field of the RPL being used by the OPNDST macro 
instruction. Subsequent I/O requests directed toward that specific terminal must 
have this CID in the I/O request's RPL. 

The NIB macro instruction causes the NIB to be built during program assembly; the 
NIB macro instruction is not executable. The NIB is built on a fullword boundary. 
A NIB can be built during program execution with the GENCB macro instruction. 
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Name 


Operation 


Operands 


[symbol] 


NIB 


[NAME=name in resource definition table] 

[ , USERFLD=fullword of terminal data] 

[,LISTEND=YES|NO] 

[, MODE=BASIC|RECORD] 

[,SDT=APPL|SYSTEM] 

[, EXLST=exit list address] 

[ , RESPLIM=response limit] 

[,NDFASYX|DFASYX] 

[,NRESPX|RESPX] 

[ , NCONFTXTICONFTXT] 

[,KEEP|TRUNC] 

[ , BLOCK|MSG|TRANS|CONTl 


[,LGOUT|NLGOUTl 
[,LGIN|NLGIN] 
[ , PROC=( \ , TMFLLINTMFLL] )] 
[,NEIB|EIB] 

[, TIMEOUTINTIMEOUT1 
[,ERPIN|NERPIN1 
[,ERPOUT|NERPOUTl 
[ , NMONITORIMONITOR1 
[,NELC|ELC] 
[,NBINARY|BINARY] 



NAME=name in resource definition table 

Associates the NIB with a terminal represented in the resource definition table. 
When used by the INQUIRE (OPTCD=APPSTAT) macro instruction, the NAME 
field associates the NIB with an application program represented in the resource 
definition table. (The resource definition table is built by the installation during 
VTAM definition.) 

Format: Use the name of the LU, TERMINAL, COMP, LOCAL, or APPL entry 
that represents the terminal or application program in the resource definition 
table.Using unframed EBCDIC characters, code this name as it appears in the 
resource definition table. 

Example: NAME=TERM13 

Note: Although this operand is optional, the NAME field should be set by the time 
the OPNDST macro instruction is issued for this NIB. One exception: When 
OPNDST with an ACCEPT processing option and an ANY option code is issued, 
the NAME field need not be set, since VTAM will place the name of the connected 
terminal in this field. 

If you omit this operand, the entire 8-byte NAME field is set to EBCDIC blanks. 

USERFLD=four bytes of terminal data 

Indicates any 4 bytes of data that the application program wants to associate with 
the terminal represented by this NIB. When you subsequently issue I/O requests for 
the terminal, VTAM will place whatever data you have set in USERFLD into the 
USER field of the I/O request's RPL. 
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The 4 bytes of data can be anything the application program chooses to associate 
with the terminal. It can be the program's own version of the terminal's symbolic 
name. This would be useful in the case of a RECEIVE or READ macro with 
OPTCD=ANY, since the setting of the USER field in the macro's RPL provides an 
efficient way for the program to establish the identity of the terminals from which 
the data was just obtained. 

Format: Code the 4 bytes of data in either character, fixed-point, or hexadecimal 
format, or, if an address is desired, code it as an A-type or V-type address constant. 
Register notation cannot be used. 

Examples; 

USERFLD=C'TERM1' 

USERFLD=F'100' 

USERFLD=X'00043E0' 

USERFLD=A(RTN1) 

USERFLD=V(EXTRTN) 

Note: Use the MODCB and CHANGE macro instructions to change the contents 
of the USERFLD field after an OPNDST macro instruction has been issued for 
the NIB. 

If you omit this operand, the USERFLD field is set to zero. 

LISTEND=YES | NO 

Allows the application program to group NIBs into lists. LISTEND=YES indicates 
that this NIB is the last in a list (or is an isolated NIB not part of a list). 
LISTEND=NO indicates that this NIB and the NIB immediately following it in 
storage are part of a NIB list. Any number of NIBs can be grouped together by 
specifying LISTEND=NO for each one except the last. 

NIB lists are used by the OPNDST macro with an ACQUIRE option code and by 
the SIMLOGON macro instruction. VTAM considers the terminals represented by 
the entire list as objects of the OPNDST or SIMLOGON macro instructions. 

When OPNDST is used for logical units, VTAM-to-logical unit I/O is performed. For 
this reason, OPNDST performance can be improved by including only one SDLC 
cluster controller's logical units in a NIB list. 

Example: The following use of the LISTEND operand effectively groups the 
Boston NIBs into one group, the Chicago NIBs into another, and defines the 
Portland NIB as a "list" of one. 

NAME=BOSTON 1 ,MODE=RECORD,LISTEND=NO 

NAME=BOSTON2,MODE=RECORD,LISTEND=YES 

NAME=CHIC AGO 1 ,MODE=RECORD,LISTEND=NO 

NAME=CHICAG02,MODE=RECORD,LISTEND=NO 

NAME=CfflCAG03,MODE=RECORD,LISTEND=YES 

NAME=PORTLAND,MODE=RECORD,LISTEND=YES 

MODE=BASIC | RECORD 

Indicates whether basic-mode macro instructions (such as READ and WRITE) or 
record-mode macro instructions (such as SEND and RECEIVE) are to be used to 
communicate with the terminal. Except for 3270 terminals, the application 
program has no choice; MODE=BASIC must be specified for all BSC and start-stop 
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terminals, and MODE=RECORD must be specified for all logical units. 3270 
terminals can be handled in either mode. 

The application program can be designed to handle both modes of terminal, since 
the INQUIRE macro instruction (OPTCD=DEVCHAR) can be used before 
connection to determine the terminal type. A simpler and better procedure, 
however, would be to maintain one ACB (application program, in effect) for BSC 
and start-stop terminals and another ACB for logical units. 

SDT=SYSTEM | APPL(Record-mode only) 

Indicates whether the application program or VTAM is to send the first 
start-data-traffic (SDT) indicator to the logical unit. If SDT=SYSTEM is used, 
VTAM automatically sends an SDT indicator as part of the connection process 
before posting the OPNDST RPL complete. If SDT=APPL is coded, VTAM does 
not send an SDT indicator until the application program tells it to do so (by issuing 
a SESSIONC macro instruction with CONTROL=SDT). 

The SDT indicator is used to permit the flow of messages and responses between 
the application program and the logical unit. See the SESSIONC macro instruction 
for more information. 

EXLST=exit list address(Record-mode only) 

Indicates an EXLST control block that contains the address of a DFASY, RESP, or 
SCIP exit-routine (or contains the addresses of any combination of these 
exit-routines). 

Exit-routines indicated by a NIB (NIB-oriented exit-routines) are scheduled when 
VTAM receives input from the logical unit associated with the NIB. If input is 
received and no NIB-oriented exit-routine is available, VTAM then satisfies any 
pending RECEIVE macros or schedules the appropriate ACB-oriented exit-routine 
(if any). 

Figure 4 shows two sets of NIB-oriented exit-routine addresses and one set of 
ACB-oriented exit-routine addresses. When input from the logical unit associated 
with NIB1 arrives, the appropriate EXLST 1 exit-routine is scheduled. When input 
from the logical unit associated with NIB2 arrives, VTAM checks EXLST2 for the 
appropriate exit-routine. If there is no exit-routine specified (which in this example 
would be true if the input was a response, since EXLST2 has no RESP entry), 
VTAM satisfies any pending RECEIVE macros or checks for an ACB-oriented 
exit-routine address in EXLSTA. When input from any other logical unit arrives, 
VTAM uses EXLSTA. 

Note: If you omit this operand, theNIB's EXLST field is set to 0. 

RESPLIM=respOnse iimit(Record-mode only) 

Indicates the maximum number of responded output requests that can be pending 
at one time. (A responded output request is a SEND with POST=RESP, 
CONTROL=DATA, and STYPE=REQ specified, and a normal response requested.) 
If RESPLIM-0 is coded, VTAM imposes no limit on the number of pending 
responded output requests. 

Note: if this operand is omitted, the RESPL1M field is set to 1. The maximum 
value that can be coded is 65,535. 
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Figure 4. ACB-Oriented and NIB-Oriented Exit-Routines 

PROC=processing option | (processing option,...) 

Indicates options VTAM is to follow for subsequent I/O requests involving the 
terminal connected using this NIB. 



Format: Code as indicated in the assembler format table above. The parentheses 
can be omitted if only one option code is selected. 



NIB 



NAME=TERM 1 3 ,MODE=RECORD, 
PROC=(DFASYX,RESPX,CONFTXT) 



NIB 



NAME=TERMI4,MODE=BASIC, 
PROC=BLOCK 



Note; Not all processing options are valid for all types of devices. See Figure 6 at 
the end of this macro instruction description to see which processing options are 
valid for the devices supported by VTAM. 

DFASYX] NDFASYX(Record-mode only) 

Indicates whether a DFASY exit-routine may be scheduled when asynchronous 

flow messages arrive in VTAM's buffers from a logical unit. 

When DFASYX is set for the logical unit's NIB and no other restrictions prevent 
the scheduling of the DFASY exit-routine, the exit-routine is scheduled. If 
NDFASYX is specified, the exit-routine is not scheduled. See the DFASY operand 
of the EXLST macro instruction for information about the DFASY exit-routine 
and the conditions that must exist before it can be scheduled. 
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RESPX | NRESPX(Record-mode only) 

Indicates whether a RESP exit-routine may be scheduled when responses arrive in 
VTAM's buffers from a logical unit. When RESPX is set for the logical unit's NIB 
and no other restrictions prevent the scheduling of the RESP exit-routine, the 
exit-routine is scheduled. If NRESPX is set, the RESP exit-routine is not scheduled. 
See the RESP operand of the EXLST macro instruction for information about the 
RESP exit-routine and the conditions that must exist before it can be scheduled. 

CONFTXT | NCONFTXT 

Indicates whether or not the data sent to or received from this terminal is to be 
considered as "confidential." If CONFTXT is specified, the buffers used to hold the 
data are cleared before they are returned to their buffer pools. For NCONFTXT, no 
such clearing is done. 

TRUNC | KEEP 

Indicates whether overlength input data is to be kept or discarded. 

When TRUNC is used, VTAM fills the input data area and discards the remainder. 
No error condition is raised. When KEEP is used, VTAM fills the input data area 
and saves the remainder for subsequent RECEIVE or READ macro instructions. 

In the basic-mode, the RPL's FDBK field indicates the presence of excess data. If 
the EOB flag is set on (DATAFLG=EOB for a TESTCB macro instruction), the 
entire block is in the input data area and no excess data remains. If the EOB flag is 
set off, there is excess data. In the record-mode, the presence of excess data can be 
determined by comparing the RPL's AREALEN field (input area size) with the 
RECLEN field (amount of incoming data). If the value in RECLEN exceeds the 
value in AREALEN, excess data exists. 

In the record-mode, the NIB's TRUNC-KEEP processing option is overriden if the 
RECEIVE RPL's KEEP-TRUNC-NIBTK option code is set to KEEP or TRUNC. 
That is, the NIB's TRUNC-KEEP processing option is effective only if the NIBTK 
option code is set in the RPL. 

BLOCK | MSG | TRANS | CONT(Basic-mode only) 

These control how many blocks of data are to be obtained from a BSC or start-stop 
terminal for a solicit operation and how acknowledgments are to be handled as each 
block arrives. 

Solicit operations are all operations conducted by VTAM to obtain data from a 
terminal to VTAM buffers. Solicitation does not involve the transfer of data from 
VTAM buffers to the application program. 

VTAM solicits data from a terminal when (1) the application program issues a 
SOLICIT macro instruction or (2) the application program issues a READ macro 
instruction with the SPEC option code in effect for the RPL. Solicitation is not 
performed in the latter case, however, if VTAM already holds data obtained from 
the terminal. 

Before reading the descriptions of BLOCK, MSG, TRANS, and CONT that follow, 
examine Figure 5. This figure illustrates a typical data transmission from a terminal 
and shows how much of it is obtained each time a SOLICIT (or READ, as qualified 
above) is executed. 
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When MSG is in effect, each 
SOLICIT obtains a message: 
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Figure 5. The Effect of BLOCK, MSG, TRANS, and CONT on Solicitation 
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BLOCK 

Either a line control response is sent to acknowledge receipt of the previous 
solicit operation, or polling is started. One block of data ending in an ECB 
line-control character (for start-stop devices) or an ETB or ETX line control 
character (for binary synchronous devices) is obtained. No response is sent when 
data is obtained as a result of the current solicit request. The data obtained by 
the current solicit request is acknowledged only when the next solicit request is 
issued. 

If the terminal represented by this NIB is a binary synchronous device, an 
authorization test is made when an OPNDST macro instruction is issued for this 
NIB. If the installation did not authorize the use of BLOCK by the application 
program (by so indicating in the application program's APPL entry during 
VTAM definition), the OPNDST macro instruction will not be executed 
successfully. (The use of BLOCK is restricted this way because it can result in 
line throughput that is very low compared to MSG, TRANS, and CONT. The 
low throughput results because the CPU, rather than just the communications 
controller, must be interrupted for each block.) 

MSG 

Blocks of data are continuously obtained until an EOT character (for start-stop 
devices) or a block containing an ETX character (for BSC) is received. In effect, 
this means that data is solicited from the terminal until an entire message has 
been received. For BSC devices, line-control responses are sent as each block is 
received, except for the last block. Its receipt is not acknowledged until the next 
solicit request is issued. 

For start-stop devices, line control responses are sent for each block, including 
the last. The procedure used to solicit data from start-stop devices when the 
MSG processing option is specified is identical to that used when TRANS 
processing option is specified. 

TRANS 

Blocks of data are continuously obtained until an EOT character is received. 
In effect, this means that data is solicited from the terminal until an entire 
transmission has been received. Line control responses are sent as each block is 
received, including the last block. Polling will not resume until the next solicit 
request is issued. 

CONT 

Blocks of data are continuously solicited from the terminal. Line-control 
responses are sent for each block received. This solicitation continues indefi- 
nitely, unless the solicit operation is canceled with the RESET macro instruction 
or the terminal is disconnected from the program. 

LGOUT | NLGOUT (Basic-mode only) 

Indicates whether or not an output operation with this terminal should be 
considered to be in error if the terminal acknowledges receipt of the data with a 
response that is preceded by leading graphic characters. 

When LGOUT is specified, a code is posted in the FDBK field of the WRITE 
request's RPL, and the leading graphic characters are held by VTAM. A READ 
request directed at the terminal causes the characters to be moved into the 
application program's storage (in the data area indicated by the AREA field of 
READ'S RPL). If leading graphic characters are received during a conversational 
write operation, the characters are passed to the application program as the input 
data. 
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When NLGOUT is specified, the output operation is completed in error if leading 
graphic characters are received in return. 

LGIN | NLGIN (Basic-mode only) 

Indicates whether or not an input operation with this terminal should be considered 

to be in error if leading graphic characters are received. 

If LGIN is specified, the presence of leading graphic characters does not constitute 
an error condition; the application program is notified of their presence by means 
of a code set in the FDBK field of the input request's RPL. 

When NLGIN is specified, the input operation is completed in error if leading 
graphic characters are detected. 

TMFLL | NTMFLL (Basic-mode only) 

Indicates whether or not the communications controller is to insert idle device 
control characters into the data sent to this terminal. TMFLL allows the 
communications controller to insert these characters. NTMFLL suppresses the 
insertion of these characters, implying that the application program will be 
supplying its own time-fill characters. Time fill is only performed for start-stop 
devices, which require special timing considerations following a carriage return and 
horizontal tab characters. 

EIB | NEIB (Basic-mode only) 

Indicates whether or not the system is to insert an EIB error information byte 
(EIB) after every intermediate transmission block (ITB) received from this terminal. 
EIB indicates that an EIB is to be inserted with each intermediate transfer block; 
NEIB suppresses the insertion of EIBs. 

If you specify insertion of EIBs, you should scan the input data for ITB characters, 
and analyze the next byte (which will be the EIB) to determine whether an error 
occurred in the intermediate block. Insertion of EIBs is appropriate when you 
expect that many ITBs will be required for a data block. If a transmission error 
occurs and you are not using EIB, you cannot determine in which ITB the error 
occurred, and so would have to request a retransmission of the entire block. 

Note: The presence of ITB characters in the input data does not depend on the 
EIB-NEIB processng option; this option only governs the presence of the EIB. The 
presence of the ITB character is a function of the terminal itself. See the XITB 
operand in the NCP Generation and Utilities Guide. 

TIMEOUT | NTIMEOUT (Basic-mode only) 

Indicates whether or not the communications controller should suppress any text 
timeout limitation that might otherwise be used with this terminal. TIMEOUT 
permits normal timeouts to occur; NTIMEOUT suppresses them. 

When TIMEOUT is in effect, the communications controller imposes a text timeout 
limitation as indicated by the installation in the terminal's TERMINAL entry. (A 
timeout limitation means that if the interval between two successive characters sent 
by a terminal exceeds a set limit, the I/O operation is terminated with an error 
condition.) NTIMEOUT provides the application program with a means of 
overriding this limitation and allowing the terminal an indefinite time period 
between characters. 
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ERPIN | NERPIN (Basic-mode only) 

Indicates whether or not system error recovery (retry) procedures are to be used if 
an I/O error occurs during an input operation with this terminal. ERPIN means that 
the error recovery procedures are to be used; NERPIN means that they are not. 

ERPOUT | NERPOUT (Basic-mode only) 

Indicates whether or not system error recovery (retry) procedures are to be used if 

an I/O error occurs during an output operation with this terminal. ERPOUT means 

that the error recovery procedures are to be used; NERPOUT means that they are 

not. 

MONITOR | NMONITOR (Basic-mode only) 

Indicates whether or not VTAM is to invoke the ATTN exit-routine (see EXLST 
macro) when this terminal causes an attention interruption. MONITOR means that 
the communication controller will monitor the terminal for attention interruptions 
while the terminal is not engaged in pending or actual I/O operations, and invoke 
the routine when an interruption is detected. 

MONITOR is valid only if the installation indicated during VTAM definition that 
the communications controller is to react to attention interruptions. If an attention 
interruption is received during an I/O operation, the I/O request ends with the 
RPL's FDBK2 field posted to indicate why. MONITOR does not apply to attention 
interruptions issued during an I/O operation. 

If NMONITOR is specified, no monitoring occurs (the attention interruption is 
ignored). 

ELC|NELC (Basic-mode only) 

Indicates whether line-control characters are to be generated for the data sent to 
this terminal. ELC signifies that the application is embedding its own line control 
characters in the data; its use prevents the system from doing so. NELC means that 
the application program is relying on the system to insert appropriate line control 
characters. See Appendix B for a list of the line control characters that are normally 
inserted. ELC can only be used if the NBINARY option code is in effect for the 
RPL. For basic-mode 3270 devices, NELC must be used. 

BINARY | NBINARY (Basic-mode only) 

Indicates how data is to be handled when a WRITE macro instruction is used to 
write to a binary synchronous device. When BINARY is specified, the data is sent in 
transparent text mode. This means that each of the line-control characters normally 
inserted by the communications controller is preceded by a DLE line control 
sequence. Any bit patterns can thus be sent, including line-control characters and 
object code. NBINARY means that the data is not sent in transparent text mode. 
Since the data will be screened for line-control characters, no bit patterns that 
happen to be line-control characters should be in the output data. (See 
"Transmission in Transparent Mode" in the NCP Generation and Utilities Guide for 
a description of transparent text mode.) 

Example NIB1 NIB NAME=KBD3270,USERFLD=A(KBDRTN), 

MODE=BASIC,LISTEND=YES 

NIB1 could represent the keyboard component of a 3270 device whose entry in the 
resource definition table is labeled KBD3270. When OPNDST is issued to connect 
this terminal to the program, the NIB field of the OPNDST' s RPL must point to 
NIB1. Since LISTEND=YES is coded only this terminal can be connected with the 
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OPNDST macro. Before OPNDST processing is completed, VTAM obtains the 
contents of NIBl's USERFLD field (which in this example is the address of a 
routine) and places it in the USER field of the OPNDST's RPL. 

NIB Fields Not Set by the All of the operands described above cause NIB fields to be set when the NIB macro 

Application Program instruction is assembled. There are additional NIB fields that can be examined by 

the application program during program execution, but cannot be set by the 
application program. VTAM uses these fields to return information to the 
application program upon completion of OPNDST processing: 

Field Name Content 

CID A 16-bit value representing the symbolic name you supplied in 

the NAME field of the NIB. This shortened name, or CID, is also 
placed in the ARG field of the RPL used by the OPNDST macro 
instruction. Subsequent I/O requests for the terminal must have 
this CID in the ARG field of the RPL used for the I/O request. 
The CID can be examined with the SHOWCB and TESTCB macro 
instructions. 

CON An indicator that is set to show that the terminal represented by 

this NIB has been connected. You can examine this field 
following OPNDST by coding CON=YES in a TESTCB macro 
instruction; an "equal" PSW condition code indicates that the 
CON field is set to YES, and the terminal is connected. This field 
is useful if you are using OPNDST to establish connection with 
more than one terminal. Should connection be established with 
some of the terminals and not others, examination of each NIB's 
CON field will tell you which terminals are connected. (If the 
terminal is not connected, the CON field is not modified.) 

DEVCHAR An 8-byte field describing the type of terminal that has been 

connected and what optional features it has. (If the terminal is 
not connected, the DEVCHAR field is not modified.) This field 
can be examined with either the SHOWCB or TESTCB macro 
instructions or with the ISTDVCHR DSECT. The DEVCHAR 
DSECT (ISTDVCHR) is described in Appendix H (Figure H-12). 

Devices Applicable for The following figure shows, for each device supported by VTAM, the processing 

Each NIB Processing Option options applicable to that device. 

An X indicates that the PROC operand value is meaningful for the device. 
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Figure 6. Devices Applicable to Each NIB Processing Option 
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OPEN -Open One or More ACBs 



The OPEN macro instruction opens (or "activates") the ACB so that the ACB and 
all subsequent requests referring to it can be identified by VTAM as representing a 
specific application program. The programmer coding the OPEN macro instruction 
indicates the ACB (or ACBs) that are to be opened. 

An ACB represents an application program, as defined by the installation. By means 
of an ACB's APPLID field the application program associates an ACB with an APPL 
entry. (A symbolic name is generated during VTAM definition by the installation 
when it defines the application program; the entry is generated with the APPL 
definition statement, and is called an APPL entry.) It is during OPEN processing 
that the association between the ACB and the APPL entry is actually made. One 
effect of this association is this: terminals directing logon requests to this APPL 
entry will in effect be directing their logon requests to the entry's associated ACB. 

If you do not specify an APPL entry in the ACB's APPLID field, VTAM assumes 
that the APPL entry will be identified via JCL. In OS/VS1 and OS/VS2, the name 
specified on the application program's EXEC statement is used; in DOS/VS, the job 
name or task ID is used. If you fail to indicate an APPL entry through either the 
APPLID field or by JCL, OPEN will not be completed successfully; and, in 
DOS/VS, if there is more than one ACB in a given task or if more than one ACB is 
opened by a single task, the OPEN is also likely to fail. For this reason, the 
application program should always supply an APPL entry in the APPLID field for 
DOS/VS. 

OPEN (and also CLOSE) must be issued in the mainline program (or in the LERAD 
or SYNAD exit-routines if they have been entered directly from the main program). 
Never issue OPEN in the RPL exit-routine or in any of the other exit-routines. 

In OS/VS1 and OS/VS2, nonprivileged tasks are permitted to issue OPEN macro 
instructions only in their job step task. Privileged tasks are allowed to open ACBs in 
any task as long as all the OPEN macro instructions are issued in the same task of 
the job step. These restrictions do not apply to subtasks in the VTAM region. 

If the APPL entry created by the installation contains a password, the ACB being 
opened must also specify that same password, or OPEN will not be completed 
successfully. 

If the ACB being opened has its MACRF field set to LOGON, logon requests are 
queued for the application program. When SETLOGON (OPTCD=START) is 
subsequently issued, queued and new logon requests will cause the LOGON 
exit-routine to be scheduled. 



Name 



Operation 



Operands 



[symbol] 



OPEN 



acb addressf , acb address] ... 



This form of OPEN is valid in DOS/VS only. 



[symbol] 



OPEN 



acb; address[ „ acb address] ... 



This form of OPEN is valid in OS/VS1 and OS/VS2 only. 
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Example 



acb address 

Indicates the ACB that is to be associated with an APPL entry. 

Format: If more than one ACB is -specified, separate each with a comma if the 
program is going to be run under DOS/VS. Separate each ACB address with two 
commas if the program is going to be run under OS/VS1 or OS/VS2. (The same 
assembler handles both VTAM and non-VTAM macro instructions. An extra 
operand can be supplied with each address for the latter, and so an extra comma is 
required for the VTAM OPEN.) 

Note: VSAM ACB addresses can also be used in the OPEN macro instruction. 
DOS/VS users can also code DTF addresses, and OS/VS1 and OS/VS2 users can 
also code DCB addresses. The addresses of different types of control blocks can be 
combined in one OPEN macro instruction, although DOS/VS users are limited to a 
total of 15 addresses. 



OPEN 123 



OPEN 



ACB1,ACB2,(7) (DOS/VS) 



OPEN 123 opens ACB1, ACB2, and the ACB whose address is contained in register 
7. Each of these ACBs is linked with an APPL entry in the resource definition table. 



Return of Status Information 



When control is returned to the instruction following the OPEN macro instruction, 
register 15 indicates whether or not the OPEN processing was completed 
successfully. Successful completion means that all ACBs specified in the OPEN 
macro instruction were opened; unsuccessful completion means that at least one 
ACB was not opened. Successful completion is indicated by a return code of in 
register 15. For DOS/VS users, register 15 is unmodified and so should be cleared 
before OPEN is executed. Unsuccessful completion is indicated by the following 
register 15 values: 



For DOS/VS 

Nonzero 

For OS/VS 
4 



12 



Meaning 

One or more ACBs (or DTFs or VSAM ACBs) were not 
successfully opened. 

Meaning 

All ACBs (or DCBs) were successfully opened, but warning 
messages were issued for one or more VSAM ACBs. 

One or more ACBs (or DCBs) were not successfully opened. If 
the error condition indicated by the unopened ACB's ERROR 
field can be eliminated, another OPEN macro instruction can 
be issued for the unopened ACBs. 

One or more ACBs (or DCBs) were not successfully opened. 
Another OPEN macro instruction cannot be issued for the 
unopened ACBs. 



If unsuccessful completion is indicated, the application program should examine 
the OFLAGS field in each ACB to determine which one (or ones) could not be 
opened. Test each OFLAGS field by coding an ACB address and OFLAGS=OPEN 
in a TESTCB macro instruction; if the resulting PSW condition code indicates an 
equal comparison, that ACB has been opened: 

TESTCB ACB=ACB4,OFLAGS=OPEN 

BE OPENOK 
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If an unequal comparison is indicated, meaning that the ACB has not been opened, 
another field in that ACB can be checked to determine the reason. This field is the 
ERROR field. Like OFLAGS, ERROR is not a field that the application program 
should modify (that is, there is no ERROR operand for the ACB macro, and thus 
none for the MODCB macro), but the application program can obtain the contents 
of this field with the SHOWCB or TESTCB macro instruction. For example: 

SHOWCB ACB=ACBl,FIELDS=ERROR,AREA=SHOWIT,LENGTH=4, 
AM=VTAM 

Note: // the ACB is already open, or if the address specified in the OPEN macro 
instruction either does not indicate an ACB or lies beyond the addressable range of 
your application program, nothing is posted in the ACB's ERROR field. Thus if 
you find one of the following return codes in the ACB's ERROR field and none of 
the specified causes apply, perhaps you are actually examining a field whose 
contents have not been modified by OPEN. An already-open ACB or an invalid 
ACB address will result in register 15 being set to 4, however. 

These are the values that can be set in the ERROR field of an ACB (except where 
noted, all values apply to DOS/VS and to OS/VS): 

OPEN has successfully opened this ACB. 

14(20) OPEN cannot be processed because of a temporary shortage of 

storage. 

24 (36) The password specified by the ACB does not match the password 

specified in the corresponding APPL entry, or the ACB does not 
specify a password and one was specified in the APPL entry. 

46 (70) OPEN was issued in an exit-routine. 

48 (72) OPEN was not issued in a job step task or in a subtask within the 

VTAM region (OS/VS 1 only). A second task in a region 
attempted to open the ACB, but the ACB was not in the VTAM 
region (OS/VS2 only). 

50 (80) VTAM has not been included as part of the operating system. The 

fault lies in your installation's system definition procedures. 

52 (82) VTAM has been included as part of the operating system, but the 

network operator has issued a HALT command, and VTAM is 
shutting down. You cannot attempt connection or communi- 
cation with any terminals. 

54(84) Either the address supplied in the ACB's APPLID field lies 

beyond the addressable range of your application program, or no 
entry could be found in the resource definition table that 
matches the name indicated by the ACB's APPLID field (or 
supplied via JCL). 

If the OPEN macro instruction was specified correctly, your 
installation may have failed to include your application program's 
symbolic name during VTAM definition, or you may have 
improperly handled the symbolic name. Refer to the description 
of the APPLID operand in the ACB macro instruction. 
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56 (86) A match for your application program's symbolic name was 

found, but it was for an entry other than an APPL entry. If you 
specified this name in the ACB's APPLID field, verify that the 
installation has supplied you with the correct name and that you 
have handled this name properly (see the APPLID operand of the 
ACB macro instruction). If the symbolic name was supplied via 
JCL, the job step name, job name, or task ID is suspect. 

58 (88) Another ACB, already opened by VTAM, indicates the same 

application program symbolic name that this ACB does. The 
installation may have assigned the same symbolic name to two 
application programs. This is valid only if the programs do not 
run (or are at least not open) concurrently. Possibly the system 
operator initiated your job or job step at the wrong time. 

5A (90) No entry could be found in the resource definition table that 

matches the name indicated by the ACB's APPLID field (or 
supplied via JCL). This error may have occurred because the 
installation deactivated the APPL entry or never created it. 

5C (92) VTAM has been included as part of the operating system, but is 

inactive. 

5E (94) The address supplied in the ACB's APPLID field lies beyond the 

addressable range of your application program. 

60 (96) An apparent system error occurred. Either there is a defect in 

VTAM's logic, or there is an error in your use of OPEN that 
VTAM did not properly detect. Save all applicable program 
listings and storage dumps, and consult your IBM Programming 
Services Representative. 

62 (98) The APPLID length indicator byte is incorrectly specified. 

64 (100) The address supplied in the ACB's PASSWD field lies beyond the 

addressable range of your application program. 

66 (102) The PASSWD length indicator byte is incorrectly specified. 

Since most of the error conditions described above result from an error in your 
application program or in the installation's definition of VTAM, there is little that 
can be done during program execution when these return codes are encountered. If, 
however, you are attempting to open more than one ACB, you may wish to check 
the ERROR field of each ACB. All ACBs whose ERROR fields are set to zero have 
been opened successfully, and your application program can proceed using those 
ACBs. 

Although the return codes following a DOS/VS OPEN are not identical to those 
following an OS/VS OPEN, the following procedure can be used to produce a 
system-independent determination of a successful or unsuccessful OPEN: 

• Zero register 1 5 before issuing OPEN. 

• Issue OPEN for only one VTAM ACB at a time. 

• If register 1 5 is zero, consider the OPEN successful. 

• If register 1 5 is nonzero, consider the OPEN unsuccessful. Examine the contents 
of the ACB's ERROR field. 
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OPNDST— Establish Connection with Terminals 



Acquiring a Terminal 



Accepting a Terminal 



Five General Types 
of OPNDST 



The OPNDST (open destination) macro instruction requests VTAM to establish 
connection between the application program and one or more terminals. 

Connection must be established with a terminal before the application program can 
communicate with that terminal. OPNDST is the sole means by which this 
connection can be requested. There are, however, two fundamentally different 
ways that OPNDST can be used to request connection. 

An application program can initiate a request that a terminal be connected to it. 
This process is called acquiring a terminal. Such a request is satisfied if the terminal 
is available; that is, is not connected to another application program and has not 
issued a logon request. This type of request is implemented by setting the 
ACQUIRE option code in the RPL used by OPNDST. The use of ACQUIRE must 
be authorized by the installation. 

If a terminal has been defined as a dial-out terminal by the installation 
(CALL=OUT), the connection request is completed immediately if the terminal is 
available, but the terminal is dialed only when an I/O request is issued for the 
terminal. 

In the second way of using OPNDST, the application can request that a terminal be 
connected to it only if the terminal requests connection with that application 
program. This process is called accepting a terminal. 

This type of connection request can be embedded in a LOGON exit-routine (see the 
EXLST macro) that is automatically entered when a terminal requests logon. This 
arrangement means that terminal logon requests can, in effect, invoke the type of 
OPNDST which will "grant" the logon request. 

This type of request is implemented as indicated above, except that the ACCEPT 
option code is set in the RPL. 

Note: When a terminal requests logon, VTAM first checks for a LOGON 
exit-routine, and invokes the routine if an active one is found. If no routine exists, 
VTAM checks for outstanding OPNDST requests (that is, OPNDSTs with ACCEPT 
and Q that have not yet been completed because no logon request has been made 
by the terminal operator). Thus a logon request will not cause a pending OPNDST 
with ACCEPT to be completed if a LOGON exit-routine is available. 

There are three versions of OPNDST with OPTCD= ACQUIRE. These versions are 
specified with two RPL option codes, CONALL and CONANY, and the LISTEND 
field of the NIB, which govern whether multiple terminals, only one terminal, or 
one specific terminal is to be connected. OPNDST with ACCEPT likewise has two 
versions, specified with two more RPL option codes, SPEC and ANY. These govern 
whether a specific terminal or any eligible terminal is to be connected. 

There are therefore a total of five general types of OPNDST. The following five 
sections indicate how you must prepare for each and what happens when the 
connection occurs. 



OPNDST with ACQUIRE, 
CONALL, and a NIB List 



Set the RPL's NIB field to point to a list of NIBs (described in the LISTEND 
operand of the NIB macro instruction), and set the ACQUIRE and CONALL 
option codes in the RPL. 
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OPNDST with ACQUIRE, 
CONANY, and a NIB List 



OPNDST with ACQUIRE 
and One NIB 



OPNDST with ACCEPT and 

ANY 



When OPNDST is issued, VTAM connects the program to all of the terminals 
represented in the NIB list that are available when OPNDST is executed. VTAM 
also: 

• Generates a CID for each connected terminal. Each CID is placed in its 
respective NIB in the CID field, where it can be obtained with the SHOWCB 
macro instruction when it is needed. The CID is not placed in the RPL's ARG 
field. (In the other forms of OPNDST, the CID is placed in the NIB and in the 
RPL.) 

• Sets a flag in each NIB indicating that the terminal is connected. This flag can be 
tested by specifying CON=YES in a TESTCB macro instruction. 

• Places the address of the first NIB of the NIB list in the AREA field of the RPL. 
(This is the same address you supplied in the RPL's NIB field; it is returned to 
you because the contents of the NIB field are modified by VTAM during 
connection.) 

Set the RPL's NIB field to point to a list of NIBs, and set the ACQUIRE and 
CONANY option codes in the RPL. 

When OPNDST is issued, VTAM connects the program to the first (and only to the 
first) available terminal represented in the NIB list. If no terminals are available, 
VTAM terminates the OPNDST request. A terminal is available if it is not 
connected to any application program and has not issued a logon request. VTAM 
also: 

• Generates a CID for the connected terminal and places it in the ARG field of the 
RPL and in the CID field of the NIB. 

• Sets a flag in the NIB that represents the connected terminal. The application 
program can locate this NIB by issuing a TESTCB macro instruction with the 
CON=YES operand for each NIB. An "equal" PSW condition code is set 
following the TESTCB macro instruction if the NIB being tested represents the 
connected terminal. 

• Places the address of the first NIB of the NIB list in the AREA field of the RPL. 
(This is the same address you supplied in the RPL's NIB field; it is returned to 
you because the contents of the NIB field are modified by VTAM during 
connection. 

Set the RPL's NIB field to point to one NIB (LISTEND field set to YES). VTAM 
connects the terminal whose symbolic name is in the NIB to the application 
program. VTAM completes the request immediately; if the terminal is not 
immediately available, it is not connected. VTAM also: 

• Generates a CID for the connected terminal and places it in the ARG field of the 
APL and in the CID field of the NIB. 

• Sets a flag in the NIB indicating that the terminal is connected. 

• Places the address of the NIB in the AREA field of the RPL. 

Set the RPL's OPTCD field to ACCEPT and ANY, and set the NIB field to point to 
a NIB. This NIB need not have any symbolic name in it, but it must at least have 
the MODE field and the LISTEND field set to YES. 

When OPNDST is issued, VTAM connects the program to any terminal that has 
directed a logon request to the program. VTAM also: 

• Places the symbolic name of the connected terminal into the NAME field of the 
NIB. 
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Generates a CID for the connected terminal and places it in the CID field of that 
NIB and in the ARG field of the RPL. 

Places the address of the NIB in the RPL's AREA field. 



OPNDST with ACCEPT and 
SPEC 



Set the RPL's OPTCD field to ACCEPT and SPEC, and set the NIB field to point to 
a NIB. This NIB must have its LISTEND field set to YES. 



When OPNDST is issued, the result will be this: VTAM connects the program to the 
specific terminal represented in the NIB if (or when) that terminal has directed a 
logon request to the program. VTAM also: 

• Generates a CID for the connected terminal and places it in the CID field of the 
NIB and in the ARG field of the RPL. 

• If you are accepting a self-generated logon request (SIMLOGON), VTAM sets a 
flag in each NIB indicating whether another application program issued a 
SIMLOGON (with Q and RELRQ in effect) while your SIMLOGON was queued. 
This flag can be tested with the NIB DSECT (ISTDNIB) described in Appendix 
H. 

• Places the address of the NIB in the RPL's AREA field. 

Besides the SPEC-ANY option code, other RPL and NIB options and fields affect 
how the OPNDST request is handled. Generally, their effect is the same as it is for 
other macro instructions that point to an RPL; see Figure 9 in the RPL macro 
instruction description for a list of these codes and fields. 



Name 


Operation 


Operands 


[symbol] 


OPNDST 


RPL=rpl address 

[ , rpl field name=new value] ... 



RPL=rpl address 

Indicates the location of the RPL to be used during OPNDST processing. 

rpl field name=new value 

Indicates an RPL field to be modified and the new value that is to be contained 
within it. If you wish to avoid the possibility of program reassembly following 
future releases of VTAM, set the RPL field with MODCB macro instructions rather 
than with the OPNDST macro instruction. 

Format: For rpl field name code the keyword of the RPL macro instruction 
operand that corresponds to RPL field to be modified. The new value can be any 
value that is valid for that operand in the RPL macro instruction, or it can indicate 
a register. 

Although any RPL operand can be specified, the following operands apply to an 
OPNDST macro instruction: 

ACB=acb address 

Indicates the ACB that identifies the application program to which the terminal is 
to be connected. 
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NIB=nib address 

Indicates the NIB whose PROC, MODE, and USERFLD attributes are to be 
assigned to the connected terminal. If OPTCD= ACQUIRE or OPTCD=SPEC, the 
NIB also identifies (via its NAME field) the terminal to be connected. 

ECB | EXIT=ecb or rpl exit-routine address 

Indicates the action to be taken by VTAM when an asynchronous (OPTCD=ASY) 
OPNDST macro instruciton is completed. The macro instruction is completed when 
the terminal has been connected. If EXIT is specified, the RPL exit-routine is 
scheduled. Otherwise the ECB is posted, and CHECK or WAIT must be used to 
determine when the posting occurs. See the RPL macro instruction for more 
information. 

OPTCD=SYN|ASY 

When the SYN option code is set, control is returned to the application program 
when the macro instruction has been completed. When ASY is set, control is 
returned as soon as VTAM has accepted the request. Once the connection has been 
established (that is, once the macro instruction has been completed), the ECB is 
posted or the RPL exit-routine is scheduled, as indicated by the ECB-EXIT field. 

OPTCD= ACQUIRE | ACCEPT 

When ACQUIRE is set, VTAM connects the terminal or terminals indicated via the 
RPL's NIB field. Only available terminals that have not issued logon requests are 
connected. When ACCEPT is set, a terminal that has issued a logon request for the 
application program is connected. 

OPTCD=CONANY | CONALL 

When CONANY is set and OPNDST (OPTCD= ACQUIRE) is issued, connection is 
made to the first available terminal of the NIB list indicated in the RPL's NIB field. 
When CONALL is set, connection is made to all the available terminals in the list. 

OPTCD=SPEC|ANY 

When SPEC is set, the terminal identified by the NIB's NAME field is connected if 
and when that terminal directs a logon request to the application program. When 
ANY is set, any terminal that has issued a logon request for the application program 
is connected. 

OPTCD=CS|CA 

Specifies the initial setting of the terminal's CS-CA mode. When CA is set, data 
obtained from the terminal can satisfy a READ or RECEIVE (OPTCD=ANY) 
macro instruction. When CS is set, only READ or RECEIVE (OPTCD=SPEC) 
macro instructions can obtain data from the terminal. 



Examples 



OPTCD=Q|NQ 

When Q is set, VTAM connects the terminal when it becomes available, no matter 
how long that might take. When NQ is set, VTAM terminates the OPNDST macro 
instruction immediately if the terminal is not immediately available. This option 
applies only when OPTCD= ACCEPT is in effect. 

Note: To avoid obscuring the differences between the basic types of OPNDST, the 
same technique is used to set the RPL fields in each example (namely, inserting 
RPL-modifiers on the OPNDST macro instruction). RPL fields could fust as well 
have been set with the MODCB macro instruction, with assembler instructions, or 
with the RPL macro instruction itself 
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This is an "ACQUIRE & CONALL" OPNDST: 

ACQALL OPNDST RPL=RPL1,NIB=NIBLIST,ACB=ACB1, 
OPTCD=(ACQUIRE, CONALL) 



NIBLST1 NIB NAME=TERMl,MODE=BASIC,LISTEND=NO 
NIB NAME=TERM2,MODE=BASIC,LISTEND=NO 
NIB NAME=TERM3,MODE=BASIC,LISTEND=YES 

ACQALL connects all of the available terminals of NIBLST1 (TERM1, TERM2, 
and TERM3) to the application program represented by ACB1. 

This is an "ACQUIRE & CONANY" OPNDST.' 

ACQANY OPNDST RPL=RPL2,NIB=NIBLST2,ACB=ACB1, 
OPTCD=(ACQUIRE,CONANY) 



NIBLST2 NIB NAME=TERMX,MODE=BASIC,LISTEND=NO 

NIB NAME=TERMY,MODE=BASIC,LISTEND=NO 

NIB NAME=TERMZ,MODE=BASIC,LISTEND=YES 

ACQANY (connects one of the terminals of NIBLST2 (TERMX, TERMY, or 
TERMZ) to the application program. The CON and CID fields are set in the NIB 
containing the name of the connected terminal. RPL's ARG field also contains the 
CID of the connected terminal. 

This is an "ACQUIRE ONE NIB" OPNDST. 

ACQONE OPNDST RPL=RPL3,NIB=NIB3,ACB=ACB1, 
OPTCD=ACQUIRE 



NIB3 NIB NAME=TERM35,MODE=BASIC 

ACQONE connects TERM35 to the application program if TERM35 is available. 

This is an "ACCEPT & ANY" OPNDST; 

ACPTANY OPNDST RPL=RPL4,NIB=NIB6,ACB=ACB1, 
OPTCD=(ACCEPT,ANY,NQ) 

NIB6 NIB MODE=RECORD 

ACPTANY connects any one terminal that has issued a logon request to the 
application program. The symbolic name of this terminal (along with its CID) is 
placed in NIB6. Since NQ is specified, the request will be terminated if no terminal 
has issued a logon request. 
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This is an "ACCEPT & SPEC" OPNDST: 

ACPTSPC OPNDST RPL=RPL5,NIB=NIB7,ACB=ACB1, 
OPTCD=(ACCEPT,SPEC,Q) 



NIB7 NIB NAME=TERM77,MODE=RECORD 

ACPTSPC connects TERM77 to the application program when a logon request is 
queued from the terminal to the application program. 

Return of Status Information After the OPNDST operation is completed, the following NIB fields are set: 

The connected terminal's CID is placed in the CID field. 

The CON field is set to YES if the terminal was in fact connected; otherwise this 
field is not modified. This field can be examined by coding CON=YES on a 
TESTCB macro instruction. 

If the ACCEPT and ANY options were in effect, the symbolic name of the 
connected terminal is placed in the NAME field. 

The characteristics of the connected terminal are indicated in the DEVCHAR 
field. The DEVCHAR codes are explained in Appendix H. 

The following fields are set in the RPL: 

If one (and only one) terminal has been connected, the CID of the connected 
terminal is placed in the ARG field. 

The address of the NIB or NIB list (as supplied by you in the NIB field) is 
returned in the AREA field. The NIB field is overlayed when the CID is placed 
in the ARG field, since the NIB and ARG fields occupy the same physical 
location in the RPL. 

The value 23 (decimal) is set in the REQ field, indicating an OPNDST request. 

The RTNCD and FDBK2 fields are set as indicated in Appendix C. 

Registers and 15 are also set as indicated in Appendix C. (Note that the 
USERFLD field is not set for OPNDST.) 
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READ— Read Data into Program Storage (Basic-mode only) 



The READ macro instruction obtains data from VTAM buffers and moves it into a 
designated area in program storage. It may or may not cause physical I/O to be 
performed. If OPTCD=ANY is in effect, the READ operation involves no I/O 
operation, but simply moves data already obtained from a terminal into program 
storage. 

If READ is being used to obtain data from a specific terminal— which means that 
the SPEC option code is in effect in the RPL— and no data from that terminal is 
available, READ first causes data to be solicited. This implied solicit operation 
works in the same manner as the solicit operation explained in the SOLICIT macro 
instruction description. 

As soon as VTAM has moved the data into program storage, it sets the RPL's 
RECLEN field to indicate how many bytes of data were moved. 

If the return code posted in register 15 indicates that the read operation was 
completed successfully, the application program should check the RPL's FDBK 
field to determine whether the data received represents the end of a message or 
transmission. (The read operation may obtain a block of data ending with an 
end-of-transmission indicator, or the indicator may come separately with the next 
read operation. In the latter case, the RECLEN field is set to when the next read 
operation is completed.) 

The user of the READ macro instruction codes the address of the RPL that will 
govern the read operation. Various fields in the RPL determine from which 
terminal the data is to be obtained, the location of the area in the program where 
the data is to be placed, and other information regarding how the read request is to 
be handled. The RPL fields can be modified with the READ macro instruction 
itself. The operands used to set these fields are indicated below. 

The TRUNC-KEEP option determines how excess data is to be handled. When 
TRUNC is in effect and there is too much incoming data to fit in the input area, the 
data is truncated and the excess is lost. If KEEP is in effect instead, and there is too 
much data, the excess if held for the time being and moved into the storage area 
when the next READ is issued. Flags set in the RPL's FDBK field (explained in 
Appendix C) indicate when the last of the excess data has been read. 



Name 


Operation 


Operands 


[symbol] 


READ 


RPL=rpl address 

[, rpl field name=new value] ... 



RPL=rpl address 

Indicates the location of the RPL that governs the read operation. 

rpl field name=new value 

Indicates an RPL field to be modified and the new value that is to be contained or 
represented within it. If you wish to avoid the possibility of program reassembly 
following future releases of VTAM, set the RPL field with MODCB macro 
instructions rather than with the READ macro instruction. 



85 



READ 



Format: For rpl field name code the keyword of the RPL macro instruction 
operand that corresponds to the RPL field being modified. ARG can also be coded. 
The new value can be any value that is valid for that operand in the RPL macro 
instruction, or it can indicate a register. The value supplied for the ARG keyword 
must indicate a register. 

Although any basic-mode RPL operand can be specified, the following operands 
apply to a READ macro instruction: 

ACB=acb address 

Indicates the ACB that identifies the application program. 

ARG=(register) 

If data is to be read from a specific terminal, the ARG field of the RPL must 
contain the CID of that terminal. Register notation is required if the CID is to be 
placed in the ARG field with this READ macro instruction. 

If data is to be read from any terminal, the ARG field's content when the macro is 
issued is irrelevant. After the data has been read, VTAM obtains the CID of the 
terminal from which the data originated and places it in the ARG field. 

AREA=input data area address 

The AREA field must contain the address of the area in the program where the data 
is to be placed. Once the data has been moved, the RPL's RECLEN field is posted 
by VTAM with the number of bytes that were placed there. 

AREALEN=length of input data area 

The AREALEN field must contain the length (in bytes) of the data area pointed to 
by AREA. This value is used by VTAM to determine whether there is too much 
incoming data to fit. If there is too much, the action indicated by the 
TRUNC-KEEP processing option is taken. 

ECB | EXIT=ecb or rpl exit-routine address 

Indicates the action to be taken by VTAM when an asynchronous (OPTCD=ASY) 
READ macro instruction is completed. The macro instruction is completed after 
the input data has been moved into the application program's storage area. If EXIT 
is specified, the RPL exit-routine is scheduled. Otherwise the ECB is posted, and 
CHECK or WAIT is required to determine when the posting occurs. See the RPL 
macro instruction for more information. 

OPTCD=SYN|ASY 

When the SYN option code is set, control is returned to the application program 
when the READ macro instruction has been completed. When ASY is set, control is 
returned as soon as VTAM has accepted the request. Once the macro instruction 
has been completed, the ECB is posted or the RPL exit-routine is scheduled, as 
indicated by the ECB-EXIT field. 

OPTCD=SPEC|ANY 

When the SPEC option code is set, data is obtained from the specific terminal 
identified in the ARG field and placed in program storage. If no previously solicited 
data from that terminal is being held in VTAM buffersa solicit operation is 
performed and the data is moved into program storage. If data is available in VTAM 
buffers, the READ macro instruction merely moves the data from the buffers to 
program storage. 
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When ANY is set, only data already available from a terminal is moved to program 
storage. The user does not identify a terminal; the data can originate from any 
terminal connected to the application program. VTAM obtains the CID of the 
terminal from which the data originated and places it in the ARG field of the RPL. 

OPTCD=CA|CS 

When the CA option code is set, there is no restriction on subsequent retrieval of 
data from the terminal that is the object of this READ macro instruction. 

When CS is set, however, any subsequent input operation will exclude that terminal 
from the group of terminals eligible for input operations. This exclusion applies 
only if the ANY option code is in effect for the subsequent operation. See the RPL 
macro instruction for more information. 



Examples 



READ1 READ RPL=RPL1,AREA=INF0,AREALEN=132, 

OPTCD=(ANY,SYN) 



INFO 



DS 



CL132 



READ1 scans VTAM buffers for data previously obtained from any connected 
terminal; and if none has yet been obtained, waits until data arrives. READ1 then 
places the data into INFO. The CID of the terminal from which the data originated 
is placed into the ARG field of RPL1. Control is not returned to the program until 
the read operation has been completed. 

READ2 READ RPL=RPL1,ARG=(3),AREA=INF0,AREALEN=132, 

OPTCD=(SPEC,SYN) 



Return of Status Information 



NIB1 
INFO 



NIB 
DS 



NAME=TERMl,MODE=BASIC 
CL132 



READ2 operates much like READ1 except that data is being read from a specific 
terminal. When the terminal was originally connected, the CID for that terminal 
was placed both in NIB1 and in the RPL used for the connection macro (OPNDST). 
This example assumes that the CID will be in register 3 when READ2 is executed. 

Once the READ operation is completed, the following RPL fields are set: 

The RECLEN field contains the number of bytes of data that were placed in the 
input area. 

The ARG field contains the CID of the terminal from which the data originated. 

The USER field is set. When a NIB is established, the user has the option of 
specifying any value in the USERFLD field of that NIB. When the READ macro 
instruction is subsequently issued for the terminal associated with that NIB, 
whatever had been placed in USERFLD by the user is placed in the USER field 
of the RPL by VTAM. 

The value 29 (decimal) is set in the REQ field, indicating a READ request. 

If READ is completed normally, as indicated by register 15 and the RTNCD 
field, the FDBK field is set indicating various attributes of the data just read. See 
Appendix C. 
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The SENSE field is set as indicated in Appendix C. 

The RTNCD and FDBK2 fields are set as indicated in Appendix C. 

Registers and 1 5 are also set as indicated in Appendix C. 
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RECEIVE— Receive Input from a Logical Unit (Record— mode only) 



The RECEIVE macro instruction obtains a message or a response that has been sent 
to the application program from a logical unit or a record-mode 3270 terminal. If 
data is received, it is placed in the input area designated by the application program. 
If a response or control indicators are received, various RPL fields are set 
accordingly. Figure 7 illustrates the major options for a RECEIVE macro 
instruction. 



A RECEIVE macro instruction can obtain any one of the following types of input (when the RECEIVE 
is issued, the application program designates the type or types that can satisfy the macro instruction): 



Receive Synchronous Flow Messages. 
RTYPE=DFSYN 
















Data Messages 




Discard excess data 
OPTCD=TRUNC 

Retain excess data 
OPTCD=KEEP 

Discard or retain as 

indicated in NIB 
OPTCD=NIBTK 


From any logical unit 

OPTCD=ANY 
From a specific logical 
unit 

OPTCD=SPEC 

Wait until input is 
available 

OPTCD=Q 
Terminate RECEIVE if 
input not available 

OPTCD=NQ 


Cancel Indicators 


Chase Indicators 


Quiesce-completed Indicators 


Ready-to-Receive Indicators 


Logical-unit-status Indicators 












Re 


ceive Asynchronous Flow Messages. 
RTYPE=DFASY 










Quiesce-at-end-of-chain Indicators 




Release-quiesce Indicators 


Shutdown-completed Indicators 


Request-shutdown Indicators 


Signal Indicators 












Re 


ceive Responses. 
RTYPE=RESP 
















Mormal Response 






E 


xception 


Response 






FME 


RRN 






FME 


RRN 




FME & RRN 


FME & RRN 































Figure 7. The Major RECEIVE Options 
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The application program designates which of the following types of input can cause 
the RECEIVE macro instruction to be completed (any combination can be 
selected): 

• Synchronous flow messages (such as data messages or ready- to-receive, chase, or 
cancel indicators). Input from a 3270 for which MODE=RECORD was specified 
is included in this category. 

• Asynchronous flow messages (such as RELQ, QEC, or signal indicators). 

• Responses to data messages. 

Only one type of input can satisfy the RECEIVE macro instruction. When the 
macro instruction is completed, the RPL's RTYPE field indicates the type actually 
received. If more than one type of input is available to satisfy a RECEIVE, the 
following priorities determine which type of input will satisfy the RECEIVE: 

1 . Asynchronous flow messages 

2. Responses 

3. Synchronous flow messages 



Name 


Operation 


Operands 


[symbol] 


RECEIVE 


RPL=rpI address 

[ , rpl field name=new value] ... 



RPL=rpl address 

Indicates the location of the RPL that describes the RECEIVE operation. 

rpl field name=new value 

Indicates an RPL field to be modified and the new value that is to be contained or 
represented within it. If you wish to avoid the possibility of program reassembly 
following future releases of VTAM, set the RPL field with MODCB macro 
instructions rather than with this RECEIVE macro instruction. 

Format: For rpl field name code the keyword of the RPL macro instruction 
operand that corresponds to the RPL field being modified. ARG can also be coded. 
The new value can be any value that is valid for that operand in the RPL macro 
instruction, or register notation can be used. 

Although any record-mode RPL operand can be specified, the following operands 
apply to the RECEIVE macro instruction: 

ACB=acb address 

Indicates the ACB that identifies the application program and through which the 
sending terminal was connected. 

ARG=(register) 

If a specific terminal is to be read (OPTCD=SPEC) the ARG operand specifies the 
register containing the CID of that terminal. If the ARG field is not modified, the 
CID already in the RPL's ARG field is used. 

AREA=input data area address 

The AREA field must contain the address of the area in the application program 

where the incoming data is to be placed. If an indicator is received instead of data, 
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the CONTROL field is posted with a value other than CONTROL=DATA, and the 
input data area is not used. Once the data has been moved, the RPL's RECLEN 
field is set by VTAM with the total number of bytes of received data. The AREA 
field is ignored if AREALEN=0. 

AREALEN=length of input data area 

The AREALEN field contains the length (in bytes) of the data area pointed to by 
AREA. This value is used by VTAM to determine if there is too much incoming 
data to fit. If there is too much, the action indicated by the TRUNC-KEEP-NIBTK 
option code is taken. 

AREALEN=0 with OPTCD=KEEP can be used to determine the amount of 
incoming data (the total length is set in RECLEN). A data area can be obtained and 
the RECEIVE macro instruction reissued. AREALEN=0 with OPTCD=TRUNC can 
be used to eliminate unwanted data messages that are queued for the application 
program. 

BRANCH=YES |NO 

If RECEIVE is to be issued in an application program that is running in privileged 
state under a TCB (OS/VS2 only), BRANCH can be set to YES. See the RPL macro 
instruction for more information. 

ECB |EXIT=ecb or rpl exit-routine address 

Indicates the action to be taken by VTAM when an asynchronous RECEIVE 
request (OPTCD=ASY) is completed. A RECEIVE request is completed when the 
message or response has been received, the data (if any) has been placed in the 
input data area, and the appropriate information has been set in the RPL. If NQ is 
specified and no input is available, RECEIVE is completed immediately. If EXIT is 
specified, the RPL exit-routine is scheduled. Otherwise, the ECB is posted and 
CHECK or WAIT must be used to determine when posting occurs. See the RPL 
macro instruction for more information. 

OPTCD=SYN|ASY 

When SYN is set, control is returned to the application program when the 
RECEIVE operation is completed. When ASY is set, control is returned as soon as 
VTAM has accepted the RECEIVE request; once the operation has been completed, 
the ECB is posted or the RPL exit-routine is scheduled as indicated by the 
ECB-EXIT field. See the RPL macro instruction for more information. 

OPTCD=CA|CS 

When the RECEIVE operation is completed, the terminal is placed into 
continue-any mode (CA) or into continue-specific mode (CS). This mode 
determines whether the next RECEIVE (OPTCD=ANY) can be satisfied by the 
terminal's next transmission. 

This option code has no effect if OPTCD=NQ and the RECEIVE is completed with 
no input. 

The switch of continue-any and continue-specific modes applies to the type of 
input specified by the RTYPE field which actually satisfies the RECEIVE. 

OPTCD=SPEC|ANY 

Indicates whether the RECEIVE macro instruction can only be satisfied by input 
from a specific terminal (SPEC) or whether it can be satisfied by input from any 
connected terminal that is in continue-any mode (ANY). 
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When OPTCD=SPEC is used, the terminal's CID must be in the RPL when the 
macro instruction is executed. When OPTCD=ANY is specified, input from a 
terminal in continue-any mode can satisfy a RECEIVE issued with RTYPE=DFASY 
or RTYPE=RESP only if PROC=NDFASYX or PROC=NRESPX (respectively) was 
specified in the NIB. 

At the completion of the RECEIVE macro instruction, the ARG field contains the 
CID of the terminal whose input satisfied the RECEIVE. 

OPTCD=TRUNC |KEEP |NIBTK 

Indicates whether overlength input data is to be truncated (TRUNC), kept (KEEP), 
or whether the PROC=TRUNC |KEEP setting in the terminal's NIB is to be used to 
determine whether the input is to be truncated or kept. 

Overlength input data is data whose length exceeds the value set in the AREALEN 
field of the RECEIVE macro instruction's RPL. When overlength data is truncated, 
the macro instruction is completed and the excess data is lost. 

When overlength data is kept, the macro instruction is completed normally, and 
RECLEN is set to indicate the total amount of data. One or more additional 
RECEIVE macro instructions are required to obtain the excess data. When 
AREALEN=0 is set, the entire input is kept. 

OPTCD=Q|NQ 

Indicates the action to be taken if no input (of the type specified by the RTYPE 
parameter) is available when the macro instruction is executed. OPTCD=Q means 
that the macro instruction is to be completed when the appropriate input 
eventually arrives. OPTCD=NQ means that the macro instruction is to be completed 
immediately with RTNCD=0 and FDBK2=6 if the input is not available. 

RTYPE=DFSYN | NDFSYN,DFASY |NDFASY,RESP |NRESP 

Indicates the types of input that can satisfy this RECEIVE macro instruction. 
DFSYN means that data and other synchronous flow messages can satisfy the 
RECEIVE macro. DFASY means that asynchronous flow messages can satisfy the 
RECEIVE macro. RESP means that responses to data messages can satisfy the 
RECEIVE macro. The negative settings (NDFSYN,NDFASY, and NRESP) indicate 
that the corresponding type of input cannot satisfy the RECEIVE macro. For 
explanations of the synchronous and asynchronous messages, see VTAM Concepts 
and Planning. 



Example 



RCV1 RECEIVE RPL=RPL1 , AREA=INBUF, AREALEN= 

RTYPE=(DFSYN,DFASY,NRESP), 
OPTCD=(ANY,Q,NIBTK) 



128, 



RCV1 is completed when an incoming message (synchronous or asynchronous 
flow) is available from any logical unit that is in CA mode. Responses cannot cause 
RCV1 to be completed. After RCV1 is completed, the application program can 
examine the CONTROL field of RPL 1 to determine the type of message received. 
If a data message is received (CONTROL=DATA), the data is placed in INBUF. The 
TRUNC-KEEP processing in the terminal's NIB determines what will be done with 
any data that exceeds 128 bytes. 



Return of Status Information 



After the RECEIVE operation is completed, the following RPL fields may be set by 
VTAM: 



92 



RECEIVE 



If RECEIVE was issued with OPTCD=ANY, the ARG field contains the CID of 
the terminal whose input causes the macro instruction to be completed. If 
RECEIVE was issued with OPTCD=SPEC, the ARG field still contains the CID 
that was placed there prior to the execution of the macro instruction. 

The RTYPE field indicates the type of input that satisfied the RECEIVE macro 
instruction. Only one type can satisfy the RECEIVE, even though more than 
one type may be eligible to satisfy the RECEIVE. Other RPL fields may be 
depending on the type of received input, as shown below: 





RTYPE= 






Field 


DFSYN 


DFASY 


RESP 


ARG 


X 


X 


X 


RECLEN 


X 


- 


- 


SEQNO 


X 


X 


X 


RESPOND 


X 


X 


X 


SWITCHC 


X 


X 


X 


USER 


X 


X 


X 


REQ 


X 


X 


X 


RTNCD 


X 


X 


X 


FDBK2 


X 


X 


X 


CHNGDIR 


X 


X 


X 


BRACKET 


X 


X 


X 


CHAIN 


X 


- 


- 


SIGDATA 


- 


X 


- 


CONTROL 


X 


X 


- 


USENSEI 


X* 


- 


X 


SSENSEI 


X* 


- 


X 


SSENSMI 


X* 


- 


X 



*For exception requests and LUS indicators only. 

The RECLEN field indicates the number of bytes of data received by VTAM. 
VTAM has moved as much of this data as possible into the input data area 
pointed to by the AREA field. If KEEP is in effect and the value in the 
RECLEN field exceeds the value in the AREALEN field, there is excess data 
present that can be obtained with more RECEIVE macro instructions. 

The SEQNO field contains the sequence number of the message or response. 

The RESPOND field indicates either the type of response that has been received 
(if RTYPE=RESP) or the type of response that the terminal expects in reply (if 
RTYPE=DFSYN). 

When a response has been received, the RESPOND field indicates the following: 



RESPOND=EX,FME,RRN 

RESPOND=EX, FME,NRRN 

RESPOND=EX,NFME,RRN 

RESPOND=EX,NFME,NRRN 

RESPOND=NEX,FME,RRN 

RESPOND=NEX,FME,NRRN 

RESPOND=NEX,NFME,RRN 



This is an exception FME and RRN response. 

This is an exception FME response. 

This is an exception RRN response. 

Invalid. 

This is a normal FME and RRN response. 

This is a normal FME response. 

This is a normal RRN response. 



RESPOND=NEX,NFME,NRRN Invalid. 

When a message has been received, the RESPOND field indicates the following (the 
value in the RTNCD field indicates whether the message is normal or an exception): 
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RESPOND=EX,FME,RRN 

RESPOND=EX,FME,NRRN 

RESPOND=EX,NFME,RRN 

RESPOND=EX,NFME,NRRN 
RESPOND=NEX,FME,RRN 

RESPOND=NEX,FME,NRRN 

RESPOND=NEX,NFME,RRN 

RESPOND=NEX,NFME,NRRN 



If this is an exception message, return an 

exception FME and RRN response. 

If this is an exception message, return an 

exception FME response. 

If this in an exception message, return an 

exception RRN response. 

Invalid. 

Return an FME and RRN response, normal or 

exception, as appropriate. 

Return a. normal or exception FME response, as 

appropriate. 

Return a normal or exception RRN response, as 

appropriate. 

Return no response of any sort. 



The USER field contains the value that was originally set in the USERFLD field of 
the terminal's NIB. 

The value 35 (decimal) is set in the REQ field, indicating a RECEIVE request. 

The RTNCD and FDBK2 fields are set as indicated in Appendix C. Registers and 
15 are also set as indicated in Appendix C. 

The CHNGDIR field indicates whether a change-direction-request or a change- 
direction-command indicator is present: 



CHNGDIR=(CMD,NREQ) 
CHNGDIR=(NCMD,REQ) 



CHNGDIR=(CMD,REQ) 
CHNGDIR<NCMD,NREQ) 



A change-direction-command indicator is pres- 
ent; the application program can now transmit 
(DFSYN only). 

A change-direction-request indicator is present; 
the application program is being prompted to 
return a change-direction-command indicator 
(RESP or DFASY only). 
Invalid. 
Neither indicator is present. 



The BRACKET field indicates whether the current bracket is beginning, ending, or 
continuing (DFSYN only): 



BRACKET=(BB,NEB) 
BRACKET=(NBB,NEB) 

BRACKET=(NBB,EB) 
BRACKET=(BB,EB) 



The input is the first of a new bracket. 

The input is a continuation of the current 

bracket. 

The input is the end of the current bracket. 

The input itself constitutes an entire bracket. 



The CHAIN field indicates the message's relative position within the chain being 
sent to the application program (DFSYN only): 



CHAIN=FIRST 
CHAIN=MIDDLE 

CHAIN=LAST 
CHAIN=ONLY 



The message is the first of a new chain. 

The message is a continuation of the current 

chain. 

The message is the last of the current chain. 

The message itself constitutes an entire chain. 



The SIGDATA field contains 4 bytes of signal information. This field is set when 
the RECEIVE is completed with CONTROL=SIGNAL. 
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The CONTROL field indicates the presence of data or control indicators in the 
message: 



Meaning 

A data message has been received. 





Possible when 


CONTROL= 


RTYPE= 


DATA 


DFSYN 


QEC 


DFASY \ 


RELQ 


DFASY j 


QC 


DFSYN J 


CANCEL 


DFSYN / 


CHASE 


DFSYN I 


LUS 


DFSYN / 


SIGNAL 


DFASY I 


RTR 


DFSYN \ 


RSHUTD 


DFASY J 


SHUTC 


DFASY / 



A control indicator has been received. 



When an exception response or logical-unit-status (LUS) indicator has been 
received, the USENSEI field contains a 2-byte user sense value. This value is tested 
as a 2-byte binary value. 

When an exception response or logical-unit-status (LUS) indicator has been 
received, the SSENSEI field may contain a system sense code or it is set to 0. See 
Appendix C for an explanation of the SSENSEI codes. 



SSENSEI=PATH 

SSENSEI=CPM 

SSENSEI=STATE 

SSENSEI=FI 

SSENSEI=RR 



An unrecoverable PATH error occurred. 

A CPM error occurred. 

A STATE error occurred. 

A Function Interpreter error occurred. 

A Request Reject error occurred. 



When the SSENSEI field is set, the SSENSMI field may also be set. The SSENSMI 
field contains a system sense modifier value; when combined with the SSENSEI 
code, a specific type of error is indentified. The SSENSMI value is tested as a 1-byte 
binary value. See Appendix C for a list of the SSENSMI values. 
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RESET— Cancel an I/O Operation (Basic— mode only) 



The RESET macro instruction can be used to: 

• Cancel an I/O operation that is pending, but is not yet in the process of being 
completed (that is, no data transfer activity has yet begun). This form of RESET 
is selected by setting the COND option code. 

• Cancel an I/O operation, whether it is pending or in the process of being 
completed, and in addition reset any error lock that may have been set for the 
terminal. This form of RESET is selected by setting the UNCOND option code. 

• Reset any error lock that may have been set for the terminal, without canceling 
any pending I/O operation. This form of RESET is selected by setting the LOCK 
option code. 

The I/O operation most likely to be pending at any given time is a solicit operation. 
Once a terminal has been polled or otherwise readied, the solicit operation is 
pending until the terminal sends the data— which could be indefinitely. 



Name 


Operation 


Operands 


[symbol] 


RESET 


RPL=rpl address 

[ , rpl field name = new value] ... 



RPL=rpl address 

Indicates the location of the RPL that governs the execution of the RESET macro 
instruction. 

rpl field name=new value 

Indicates an RPL field to be modified and the new value that is to be contained or 
represented within it. If you wish to avoid the possibility of program reassembly 
following future releases of VTAM, set the RPL field with MODCB macro 
instructions rather than with the RESET macro instruction. 

Format: For rpl field name code the keyword of the RPL macro instruction 
operand that corresponds to the RPL field being modified. ARG can also be coded. 
The new value can be any value that is valid for that operand in the RPL macro 
instruction, or it can indicate a register. The value supplied for the ARG keyword 
must indicate a register. 

Although any basic-mode RPL operand can be specified, the following operands 
apply to a RESET macro instruction: 

ACB=acb address 

Indicates the ACB that identifies the application program. 

ARG=(register) 

Indicates the register containing the terminal's CID. The ARG field of RESET's 
RPL must contain the CID of the terminal whose I/O operation is to be canceled or 
whose error lock is to be reset. Register notation is used to place the CID into the 
ARG field with this RESET macro instruction. Note that you do not issue RESET 
for a particular request; you issue RESET for a specific terminal, and let VTAM 
deal with any requests that may that may be outstanding for that terminal. 
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ECB | EXIT=ecb or rpl exit-routine address 

Indicates the action to be taken by VTAM when an asynchronous (OPTCD=ASY) 
RESET macro instruction is completed. For OPTCD=LOCK, the macro instruction 
is completed when the error lock has been reset. For OPTCD=COND or 
OPTCD=UNCOND, the macro instruction is completed when all outstanding I/O 
requests to the terminal have been posted complete. If EXIT is specified, the RPL 
exit-routine is scheduled. Otherwise the ECB is posted, and CHECK or WAIT must 
be used to determine when the posting occurs. See the RPL macro instruction for 
more information. 

OPTCD=SYN | ASY 

When the SYN option code is set, control is returned to the application program 
when the macro instruction has been completed. When ASY is set, control is 
returned as soon as VTAM has accepted the request. Once the macro instruction 
has been completed, the ECB is posted or the RPL exit-routine is scheduled, as 
indicated by the ECB-EXIT field. 

OPTCD=CA|CS 

When CA is set, data obtained from the terminal can satisfy a READ macro 
instruction. When CS is set, only READ (OPTCD=SPEC) macro instructions can 
obtain data from the terminal. See the RPL macro instruction for more 
information. 

OPTCD=COND | UNCOND | LOCK 

COND 

RESET cancels any I/O operation that has been initiated, but for which no data has 
been transferred. If data transfer is in progress when RESET is executed, the RPL's 
RTNCD field is set to indicate that cancellation did not occur. If a read or write 
operation is pending, that operation is posted as completed, and both register and 
the RTNCD and FDBK2 fields of that request's RPL indicate that RESET caused 
the premature completion of the operation. 

OPTCD=COND cannot be used if an error lock has been set for the terminal. Use 
one of the other forms of RESET to reset the error lock. (FDBK2 codes returned 
from the I/O request indicate whether the I/O operation failed and, if so, whether 
an error lock was set.) OPTCD=COND is appropriate when the application program 
wants to write to a terminal only if no data is being sent (and can tolerate a 
resulting delay). 

The RESET operation is completed when all of the pending I/O operations for the 
terminal have been canceled (or is completed immediately if VTAM determines that 
I/O is in progress). 

UNCOND 

RESET cancels any I/O operation, pending or otherwise, that is being performed 
with the terminal. Any data that a canceled solicit operation has already brought 
into VTAM storage buffers is available for retrieval by the application program. 
Data that is being sent or is about to be sent, however, may be lost. When a solicit, 
read, or write operation is canceled, that operation is posted as completed, and the 
RTNCD and FDBK2 fields of its RPL indicate that RESET caused the premature 
completion of the operation. OPTCD=UNCOND also causes RESET to perform the 
same resetting operation indicated below with OPTCD=LOCK. OPTCD=UNCOND 
is appropriate when a terminal is being solicited for input, but the application 
program wants to immediately write to the terminal without delay (and can 
tolerate a possible loss of data). 
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OPTCD=UNCOND causes the communications controller to do the following: For 
start-stop devices with the break feature a reset immediate is sent, and for other 
start-stop devices, a reset ahead-of-command is sent; for BSC devices, a reset orderly 
(RVI) is sent. Any outstanding WRITE operations to the terminal are posted 
completed, with their return codes indicating that the operation was canceled by 
RESET. 

The RESET operation is completed when all of the I/O requests for the terminal 
have been canceled. 

If a read request is pending for a binary synchronous device at the time RESET is 
issued, the application program must continue to issue read requests until an EOT is 
received. (The FDBK field is set upon receipt of an EOT.) If a read request is 
pending for a start-stop device without the break feature, the application program 
must continue to issue read requests until the amount of data solicited from the 
device has been obtained. That is, if PROC=TRANS is in effect for SOLICIT, reads 
must be issued until an EOT is received; if PROC=MSG is in effect, reads must be 
issued until EOM is received, and so forth. If a read request is pending for a 
start-stop device with the break feature, the application program must allow that 
read to complete before issuing RESET, but no further reads need be issued. (If 
that read results in excess data being received, a second read to obtain that excess 
data would have to be issued, however, before RESET could be issued.) 

LOCK 

RESET resets an error lock that has been set for the terminal. The RESET 
operation is completed as soon as the error lock is reset. Error locks are set by a 
communications controller when it determines that it should not or cannot 
continue to communicate with a terminal until the application program determines 
the next action to be performed. 

If several WRITE requests have been issued and an error lock is set before all have 
been completed, resetting the error lock restarts the remaining WRITE operations. 

You can determine that an error lock has been set by examining the RTNCD and 
FDBK2 fields of each I/O request's RPL. If RTNCD=12 and FDBK2=0, an error 
lock has been set. 

Note: This type of RESET should not be used if the error lock was set while a DO 
macro instruction involving more than one LDO was being executed. Use RESET 
with OPTCD=UNCOND instead. 

Example RESET 1 RESET RPL=RPLl,ARG=(3),ECB=ECBWORD, 

OPTCD=(ASY,UNCOND) 



ECBWORD DC F(0) 

RPL1 RPL ACB=ACB1,AM=VTAM 

RESET 1 cancels any I/O operation pending or in progress for the terminal whose 
CID has been loaded into register 3. As soon as the cancellation has been scheduled, 
control is returned to the next instruction after RESET1. To verify that the 
cancellation has been completed, a CHECK macro instruction must be issued to 
determine if ECBWORD has been posted. 
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Return of Status Information After the operation is completed, the following RPL fields are set: 

The value 18 (decimal) is set in the REQ field, indicating a RESET request. 

The USER field is set. 

The RTNCD and FDBK2 fields are set as indicated in Appendix C. Registers 
and 15 are also set as indicated in Appendix C. 
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RESETSR-Cancel RECEIVE Operations and Switch a Logical Unit's CS-CA Mode 
(Record-mode only) 



The RESETSR macro instruction is used to change a specified terminal's 
continue-any or continue-specific mode and cancel RECEIVE macro instructions 
that are outstanding for the terminal. Figure 8 summarizes the functions of 
RESETSR and their associated operands. 



Changing CA-CS Mode 



RESETSR changes a terminal's continue-any (CA) or continue-specific (CS) mode 
in the same manner as do SEND and RECEIVE macro instructions. 



When the CA-CS option code is set to CA, RESETSR places the terminal into 
continue-any mode if it is not already in that mode. Continue-any mode means that 
RECEIVE macro instructions issued in the any-mode (OPTCD=ANY) as well as in 
the specific-mode (OPTCD=SPEC) can be satisfied by input from the terminal. 

When the CA-CS option code is set to CS, RESETSR places the terminal into 
continue-specific mode, if it is not already in that mode. Continue-specific mode 
means that only RECEIVE macro instructions issued in the specific-mode can be 
satisfied by input from the terminal. 



RESETSR is used to switch CA-CS mode 



Continue-any mode: OPTCD 


=CA 




For which type(s) 
of input ? 


Synchronous Flow Messages: RTYPE=DFSYN 


Asynchronous Flow Messages: RTYPE=DFASY 


Responses: RTYPE=RESP 









To what ? 



Continue-specific mode: 

For which type(s) 
of input ? 


OPTCD=CS 






Synchronous Flow Messages: RTYPE=DFSYN 


Asynchronous Flow Messages: RTYPE=DFASY 


Responses: RTYPE=RESP 









And to cancel RECEIVE macro instructions. 



For which type(s) 
of input ? 






Synchronous Flow Messages: RTYPE=DFSYN 


Asynchronous Flow Messages: RTYPE=DFASY 


Responses: RTYPE=RESP 







Figure 8. The Major RESETSR Options 
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A terminal's CA-CS mode does not apply generally to all input from the terminal, 
but applies individually for the three types of input from the terminal- 
synchronous flow messages, asynchronous flow messages, and responses. The 
application program selects the type or types of input by setting the RPL's RTYPE 
field. 

For example, suppose that RESETSR is issued with the CA-CS option set to CS 
(change to CS mode), and the RTYPE field set to DFASY (asynchronous flow 
messages). When the RESETSR macro instruction is completed, the terminal is 
placed in continue-specific mode for asynchronous flow messages. This would mean 
that asynchronous flow messages sent by the terminal could not satisfy a RECEIVE 
issued in the any-mode; they could only satisfy a RECEIVE macro instruction 
issued in the specific-mode for a asynchronous flow messages. 



Canceling 
RECEIVE Requests 



The RTYPE field of the RESETSR RPL indicates the type or types of RECEIVE 
requests that are canceled. For every RTYPE specified in the RESETSR macro, 
VTAM sets the corresponding RTYPE parameter to its negative value (NDFSYN, 
NDFASY, NRESP) in each pending RECEIVE. A RECEIVE is canceled if the 
combination of input types specified in its RPL is included in those specified in the 
RESETSR macro instruction. 



For example, suppose that these three specific RECEIVE macro instructions are 
pending: 



RCV1 RECEIVE 
RCV2 RECEIVE 
RCV3 RECEIVE 



RPL=RPL1 ,RTYPE=(DFSYN,NDFASY,NRESP) 

RPL=RPL2,RTYPE=(DFSYN,DFASY,NRESP) 

RPL=RPL3,RTYPE=(DFSYN,DFASY,RESP) 



The following RESETSR macro instruction would change all DFSYN values to 
NDFSYN and all DFASY values to NDFASY: 



RST RESET 



RPL=RPL4,RTYPE=(DFSYN,DFASY) 



Since the three RECEIVE macros would in effect now be set as follows, RCV1 and 
RCV2 would be canceled (all three RTYPE parameters are negative) but RCV3 
would not be canceled: 



RCV1 RECEIVE 
RCV2 RECEIVE 
RCV3 RECEIVE 



RPL=RPL1 ,RTYPE=(NDFSYN,NDFASY,NRESP) 
RPL=RPL2,RTYPE=(NDFSYN,NDFASY,NRESP) 
RPL=RPL3,RTYPE=(NDFSYN,NDFASY,RESP) 



When a RECEIVE is canceled, its RPL is posted complete (that is control is 
returned, its ECB is posted, or its exit-routine is scheduled) with RTNCD=12 and 
FDBK2=10. The OPTCD=CA | CS setting of each canceled RPL is ignored. 



Name 


Operation 


Operands 


[symbol] 


RESETSR 


RPL=rpl address 

[ , rpl field name=new value] ... 
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RPL=rpl address 

Indicates the location of the RPL that describes the RESETSR operation. 

rpl field name=new value 

Indicates an RPL field to be modified and the new value that is to be contained or 
represented within it. If you wish to avoid the possibility of program reassembly 
following future releases of VTAM, set the RPL field with MODCB macro 
instructions rather than with this RESETSR macro instruction. 

Format: For rpl field name code the keyword of the RPL macro instruction 
operand that corresponds to the RPL field being modified. ARG can also be coded. 
The new value can be any value that is valid for that operand in the RPL macro 
instruction, or register notation may be used. Although any RPL operand can be 
specified, the following operands apply to the RESETSR macro instruction: 

ACB=acb address 

Indicates the ACB that identifies the application program and was used when the 
terminal was connected. 

ARG=(rejpster) 

The RESETSR macro instruction is always directed toward a specific terminal. The 
ARG operand specified the register containing the CID of that terminal. If the ARG 
field is not modified, the CID already in the RPL's ARG field is used. 

ECB | EXIT=ecb or rpl exit-routine address 

Indicates the action to be taken by VTAM when an asynchronous (OPTCD=ASY) 
RESETSR request is completed. A RESETSR request is completed when the 
appropriate macro instructions have been canceled, and the terminal's CA-CS mode 
has been set. If EXIT is specified, the RPL exit-routine is scheduled. Otherwise the 
ECB is posted and CHECK or WAIT must be used to determine when posting 
occurs. See the RPL macro instruction for more information. 

BRANCH=YES |NO 

If RESETSR is to be issued in an application program that is running in privileged 
state under a TCB (OS/VS2 only), BRANCH can be set to YES. See the RPL macro 
instruction for more information. 

OPTCD=SYN|ASY 

When SYN is set, control is returned to the application program when the 
RESETSR operations have been completed. When ASY is set, control is returned as 
soon as VTAM has accepted the RESETSR request; once the operations have been 
completed, the ECB is posted or the RPL exit-routine is scheduled, as indicated by 
the ECB-EXIT field. See the RPL macro instruction for more information. 

OPTCD=CA|CS 

This option code determines whether the terminal is placed in continue-any (CA) or 
continue-specific (CS) mode. The new CA-CS mode applies to the type of input 
specfied in the RTYPE field. CA-CS mode is explained in the RPL macro 
instruction and in VTAM Concepts and Planning. 

RTYPE=(DFSYN |NDFSYN,DFASY |NDFASY,RESP |NRESP) 

The RTYPE operand indicates the type of input to be affected by the resetting of 
the terminal's continue-any or continue-specific mode and which outstanding 
RECEIVE macros are to be canceled. (Continue-any mode means that input from 
the terminal can satisfy a RECEIVE issued in the any-mode; continue-specific mode 
means that it cannot.) 
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DFSYN— the terminal's CA-CS mode applies to synchronous flow messages; 
NDFSYN means that synchronous flow messages are not affected. 

DFASY— the terminal's CA-CS mode applies to asynchronous flow messages; 
NDFASY means that asynchronous flow messages are not affected. 

RESP— the terminal's CA-CS mode applied to response units; NRESP means that 
responses are not affected. 

The RTYPE operand also; designates the type of pending RECEIVE to be canceled. 
A RECEIVE request is canceled, however, only if all of the input types specified 
for the RECEIVE requests's RTYPE field are also included among those specified 
on the RESETSR request's RTYPE field. When the RECEIVE request is canceled, 
its RPLis posted complete with RTNCD-12 and FDBK2=10. 

DFSYN— pending RECEIVE requests for data messages or other synchronous flow 
messages are canceled; NDFSYN means that RECEIVE requests for this type of 
input are not canceled. 

DFASY— pending RECEIVE requests for asynchronous flow messages are canceled; 
NDFASY means that that RECEIVE requests for this type of input are not 
canceled. 

RESP— pending RECEIVE requests for responses are canceled; NRESP means that 
RECEIVE requests for responses are not canceled. 



Example 



Return of Status Information 



RST1 RESETSR RPL=RPL1 ,OPTCD=C A, 

RTYPE=(DFSYN,NDFASY,NRESP) 

RST1 cancels pending RECEIVE (OPTCD=SPEC) macro instructions for the 
terminal identified in RPLl's ARG field. RST1 also switches the terminal's CA-CS 
mode for synchronous flow messages to continue-any (CA) mode. That is, a 
RECEIVE macro instructions (RTYPE=DFSYN) can obtain synchronous flow 
input from the terminal. The terminal's CA-CS mode for DFASY and RESP input is 
not affected. 

After the RESETSR operation is completed, the following RPL fields are set: 

The value 36 (decimal) is set in the REQ field, indicating a RESETSR request. 

The value originally set in the USERFLD field of the terminal's NIB is set in the 
USER field of the RPL. 

The RTNCD and FDBK2 fields are set as indicated in Appendix C. 

Registers and 1 5 are also set as indicated in Appendix C. 
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RPL— Create a Request Parameter List 



Every request that an application program makes for connection or for I/O 
operations must refer to an RPL. A request parameter list, or RPL, is a control 
block used by the application program to describe the requests it makes to VTAM. 
The application program may, for example, simply issue a RECEIVE macro and 
indicate an RPL; it is the RPL that shows VTAM which terminal the input is to be 
obtained from, where the input data is to be placed, how the application program is 
to be notified when the operation is completed, and a variety of other options to be 
followed while the request is being processed. If the RPL already contains a request 
code in its REQ field, an EXECRPL macro can be used in place of the RPL-based 
macro indicated in REQ. 

An application program can create many RPLs; a separate RPL can, in fact, be 
created for every connection and I/O request in the application program. Or, at 
the other extreme, one RPL could serve for all connection and I/O requests in the 
program (assuming that all the requests were synchronous— that is, issued with 
OPTCD=SYN set). This multiple use of an RPL is possible because each connection 
and I/O request can itself modify fields of the RPL to which it points. The RPL can 
thus be thought of as the list form of all of the connection and I/O macros. 

The RPL macro instruction builds an RPL during assembly. The RPL is built on a 
fullword boundary. An RPL can also be generated during program execution with 
the GENCB macro instruction. See GENCB for a description of this facility. 

Requests for RPL modification can be made as part of a connection or I/O macro, 
or by the MODCB macro instruction. Either way involves naming an RPL field and 
specifying its new value. It is useful to keep in mind that every operand of the RPL 
macro represents a field in the RPL it generates. Subsequent requests to modify any 
RPL field use the keyword of the operand corresponding to the field being 
modified. 

Assumed (default) values for most of the RPL fields are set by VTAM when the 
RPL is initially assembled or generated. These assumed values are noted in the 
operand descriptions below. Once an RPL field has been set, however, the field 
always retains that setting until the application program sets it again. (Three 
exceptions to this rule-the SSENSEO, SSENSMO, and USENSEO fields-are noted 
below.) 

Although all of the RPL operands are optional (with the exception of AM=VTAM), 
all of the RPL-based macro instructions require that various RPL fields be set when 
the macro instruction is executed. These fields are identified in Figure 9 at the end 
of this macro instruction description. 
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Name 



[symbol] 



Operation 



RPL 



Operands 



AM=VTAM 

, ACB=acb address] 

, NIB=nib address] 

, AREA=data area address] 

, AREALEN=data area length] 

, RECLEN=data length] 

, AAREA=alternate data area address] 

, AAREALN=alternate data area length] 

, ECB=event control block address ) 

, EXIT=rpl exit-routine address J 

[,BRANCH=YES 1 |NO] 
, SEQNO=sequence number] 
[,POST=SCHED|RESP] 

, RESPOND=(EX|NEX, FMEJNFME, RRN|NRRN)] 
, CONTROL=(DATA|QEC|RELQ|QC|CANCEL| 

CHASE|SHUTD|BID|LUS|SDT| 

CLEARISTSN)] 
[ , CHAIN=FIRST|MIDDLE|LAST|ONLY] 
[, CHNGDIR=(CMD|NCMD, REQ1 NREQ )] 
LBRACKET=(BB 1NBB, EB 1NEB) ] 
[, RTYPE=(DFSYN|NDFSYN, DFASY 1NDFASY , 

RESPINRESP)] 
f,STYPE=REQ|RESP] 
[ , SSENSEO=CPM|STATE|FI|RR] 
[ , SSENSMO=system sense modifier value] 
[ , USENSEO=user sense value] 
[ , IBSQAC=SET|TESTSET|INVALID|IGNORE] 
[ , OBSQAC=SET|TESTSET|INVALID|IGNORE] 
[ , IBSQVAL=inbound sequence number] 
[, OBSQVAL=outbound sequence number] 

[,NIBTK|TRUNC|KEEP] 

[, NFMHDR |FMHDR] 

[,CONALL|CONANY] 

[,ACCEPT| ACQUIRE] 

L SPEC [ANY] 

f , QUIESCE ISTOPISTART] 

f, RELEASE [PASS] 

[ , LOGONMSG IDEVCHAR 1 

COUNTS ITERMS | APPSTATI 
[,OPTCD=( CIDXLATE|TOPLOGON| )] 

BSCID] 

[,SYN|ASY] 

[,CA|CS] 

[,BLK|LBM|LBT] 

[,NCONV|CONV] 

[, COND 1UNCONDILOCK] 

[,NERASE|ERASE|EAU] 

L RELRQ INRELRQ] 

[,Q|NQ] 



1 The BRANCH=YES operand is valid only in OS/VS2. 
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AM=VTAM 

Indicates that a VTAM RPL is to be built. This operand is required. 

ACB=acb address 

Associates the request that will use this RPL with an ACB. 

Format: Expressions involving registers cannot be used with the RPL macro 
instruction. 

If you omit this operand, the ACB field is set to 0. 

NIB=nib address 

Identifies the NIB whose .NAME fiejd indicates the terminal that is to be the object 
of an OPNDST, CLSDST, INQUIRE, INTRPRET, or SIMLOGON macro 
instruction. 

Although these macro instructions use a NIB address to indicate a terminal, the 
READ and RECEIVE (OPTCD=SPEC) and the SEND, RESETSR, SESSIONC, 
WRITE, SOLICIT, RESET, and DO macro instructions use a CID to indicate a 
terminal (and CLSDST, along with some forms of INQUIRE, work either way). 
CIDs (communication identifiers) are supplied to the application program upon 
completion of an OPNDST macro instruction. The CID and the NIB address occupy 
the same physical field in the control block. VTAM can distinguish between a NIB 
address and a CID only through a particular bit set in the field. For this reason, the 
field is called the NIB field when a NIB address is being inserted into it, and an 
ARG field when a CID is being inserted into it. When NlB=address appears on a 
CHANGE macro instruction, for example, the bit is set to indicate that the field 
contains a NIB^ddjcessv^When ARG=(register) is coded on a READ macro 
instructioryrfef afxample: bethel bit is set to indicate that the field contains a CID. 
(Note tha|: agister notation must he. used with ARG, since CIDs are not available 
until program execution.) 

n The point to remember when dealing with the NIB- ARG field is this: Since only 
one physical field is involved, always use the NIB keyword to insert a NIB address 
and always use the ARG keyword to insert a CID. This rule also applies to the 
GENCB and MODCB macro instructions. 

Format: Expressions involving registers cannot be used with the RPL macro 
instruction. 

If you omit this operand, the NIB field is set to 0. 

AREA=data area address 

When used by a SIMLOGON, INTRPRET, or a CLSDST macro with a PASS option 
code, AREA indicates the address of an area containing a logon message. 

When used by a SEND, RECEIVE, READ, or WRITE macro instruction, AREA 
indicates the address of an area in program storage into which data is to be read or 
from which data is to be written. 

When used by an INQUIRE macro instruction, AREA indicates where the data 
obtained by INQUIRE is to be placed. 

When used by a DO macro instruction, AREA contains the address of an LDO. 



106 



RPL 



The AREA field is also set upon return from an OPNDST (OPTCD=ACQUIRE) 
macro instruction, indicating the address of a NIB or list of NIBs. The AREA field 
is not set by the application program before OPNDST is issued. 

Format: Expressions involving registers cannot be used with the RPL macro 
instruction. 

If you omit this operand, the AREA field is set to 0. 

AREALEN=data area length 

Function: Indicates the length (in bytes) of the data area identified by the AREA 
operand. The AREALEN operand is meaningful only for input operations or for 
the INQUIRE macro instruction; VTAM uses this length to determine whether the 
data it is placing in the area is too long to fit. For the RECEIVE macro instruction, 
AREALEN=0 means that no input data area is available. 

Format: Expressions involving registers cannot be used with the RPL macro 
instruction. 

If you omit this operand, the AREALEN field is set to 0. 

RECLEN=data length 

When used by a SIMLOGON or INTRPRET macro instruction, or by a CLSDST 
macro with the PASS option code, RECLEN indicates the length (in bytes) of a 
logon message or sequence contained in the area indicated by the AREA operand. 

When used by a RECEIVE, SEND, READ, or WRITE macro instruction, RECLEN 
indicates the length (in bytes) of the data that begins at the address indicated by 
AREA. For SEND and WRITE operations, RECLEN provides the application 
program a means of telling VTAM how much data is to be transferred. For 
RECEIVE and READ operations, the RECLEN operand has no meaning; but the 
four-byte field in the RPL corresponding to RECLEN is set by VTAM when the 
input operation is finished to indicate the length of data that VTAM has just placed 
into AREA (for READ) or the total length of available data (for RECEIVE). For a 
conversational WRITE, which includes both an input and an output operation, 
RECLEN indicates the amount of data to be written. VTAM will post the length of 
the incoming data in an RPL field called the ARECLEN field. 

When a RECEIVE operation is completed and excess data is available (that is, 
KEEP is in effect and the message is too long to fit in the input area), RECLEN 
contains the total length of the message. The application program can reissue the 
RECEIVE until the value in RECLEN is less than the value in AREALEN. The 
RECLEN field is also set upon return from the SETLOGON macro instruction, 
indicating the number of logon requests . currently queued for the application 
program. The RECLEN field is not set by the afplication program before 
SETLOGON is issued. 

The application program can obtain the value in the RECLEN field by issuing a 
SHOWCB macro, or it can test the contents of RECLEN against a fixed value with 
the TESTCB macro instruction. For example: 

SHOWCB RPL=(1),AM=VTAM OBTAIN THIS RPL'S... 

FIELDS=RECLEN, ...RECLEN FIELD... 

AREA=WORKAREA, ...AND PLACE IT IN WORKAREA... 

LENGTH=4 . ..WHICH IS FOUR BYTES LONG. 
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Format: Expressions involving registers cannot be used with the RPL macro 
instruction. 

If you omit this operand, the RECLEN field is set to 0. 

AAREA=alteraate data area address 

When used by a CLSDST macro instruction with a PASS option code, AAREA 
indicates the location of an 8-byte area containing the symbolic name of the 
application program to which a logon request is to be directed. The EBCDIC name 
should be left-justified and padded to the right with blanks. This name is the same 
as the name of the application program's APPL entry in the resource definition 
table. 

When used by an INTRPRET macro instruction, AAREA indicates a work area 
where VTAM places the interpreted data sequence. See the INTRPRET macro 
instruction for details. 

When used by a WRITE macro instruction with a CONV option code, AAREA 
indicates an input area in the application program into which data is to be placed. 
This type of operation is called a conversational write operation and is described in 
the WRITE macro instruction description. 

If you omit this operand, the AAREA field is set to 0. 

Format: Expressions involving registers cannot be used with the RPL macro 
instruction. 

AAREALN=alternate data area length (Basic-mode only) 

Indicates the length (in bytes) of the data area identified by the AAREA operand. 
When AAREA is used as an input area for a conversational WRITE macro 
instruction, VTAM will use this length to determine whether the data to be placed 
there is too long to fit. 

Format: Expressions involving registers cannot be used with the RPL macro 
instruction. 

If you omit this operand, the AAREALN field is set to 0. 

ECB=event control block address 

Indicates the location of an event control block (ECB) to be posted by VTAM 
when the connection or I/O request associated with this RPL is completed. The 
ECB can be any fullword of storage aligned on a fullword boundary. 

Format: Expressions involving registers cannot be used with the RPL macro 
instruction. 

Note: If asynchronous handling of the connection or I/O request has been 
specified (ASY option code in the RPL) issue a CHECK macro to determine 
whether posting has occurred. 

If the ECB operand is specified, the EXIT operand must not be specified. These 
represent two alternative ways for the application program to be notified when the 
asynchronous operation is completed. (EXIT indicates a routine to be entered when 
the operation is completed.) 
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If neither an ECB nor an EXIT routine is indicated, the ECB field in the RPL is 
used as an ECB, rather than as the address of an ECB. 

EXIT=rpl exit-routine address 

Indicates the address of a routine to be scheduled when the request represented by 
this RPL is completed. 

If the SYN option code has been specified, this operand is not used; should you 
specify an address anyway, the address may be modified before the synchronous 
request completes. The RPL exit-routine is scheduled only if asychronous handling 
of the request has been specified. 

When the routine receives control, it is passed the address of the RPL in register 1 . 
The RTNCD and FDBK2 fields will indicate the status of the request. 

The RTNCD- FDBK2 examination could reveal that the request was completed with 
a logical or physical error. You should issue CHECK in the RPL exit-routine; this 
will schedule the LERAD or SYNAD exit-routines, if appropriate, as well as set the 
RPL to an inactive state. (LERAD and SYNAD exits are discussed in the EXLST 
macro instruction description.) Never issue the CHECK in your main program 
unless you are sure that CHECK will be executed after the RPL exit-routine is 
scheduled. 

When the RPL exit-routine receives control, these general purpose registers contain 
the following (2-13 are unpredictable): 

Register 1: the address of the RPL associated with the request whose completion 
has caused the RPL exit -routine to be entered. 

Register 14: the address in VTAM to which the RPL exit-routine must branch 
when it is through processing. (For programs running under OS/VS2 in a 
privileged state, the address is an address in the OS/VS2 dispatcher, not in 
VTAM.) 

Register 15: the address of the RPL exit-routine. 

No register save area is provided upon invocation of the RPL exit-routine. 

If the EXIT operand is specified, the ECB operand must not be specified. (The 
EXIT field and the ECB field occupy the same field in the RPL.) 

BRANCH=YES (NO 

For OS/VS2 application programs running in privileged state under a TCB, 
BRANCH indicates the type of processing to be used when a SEND, RECEIVE, or 
RESETSR macro instruction is issued. 

YES(OS/VS2 only) 

When the macro instruction is issued, VTAM processes the macro instruction in an 
optimized high-priority manner. (For OS/VS2 programs running in privileged state 
under an SRB, rather than under a TCB, the macros are processed in this manner 
automatically regardless of the actual setting of the BRANCH field.) 

NO 

When the macro instruction is issued, VTAM does not process the macro 
instruction in an optimized high-priority manner. For DOS/VS and OS/VS1 
programs, all requests are handled as though BRANCH=NO had been specified, 
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regardless of the actual setting of the BRANCH field. 

SEQNO=sequence number (Record-mode only) 

Indicates the sequence number of a response. When the application program sends a 
response to a terminal, the sequence number of the message being responded to is 
placed in the SEQNO field. This field is also set by VTAM on completion of a 
SEND (STYPE=REQ) and on completion of a RECEIVE. 

POST=SCHED|RESP (Record-mode only) 

This field is set when the application program sends a data message to a terminal 
and requests a normal response. When POST=SCHED is used (scheduled output) 
the SEND is completed as soon as the output data area is free. The application 
program must issue a RECEIVE to obtain the response to the message. When 
POST=RESP is used (responded output) the SEND is not completed until a 
response to the message is returned. The response information is posted in the RPL 
fields of the SEND RPL. 

RESPOND=(EX |NEX,FME |NFHE,RRN |NRRN) (Record-mode only) 

When a response is sent, the RESPOND field indicates the type of response— normal 
(NEX) or exception (EX)— and the source of the response— FME, RRN, or both 
FME and RRN. 

When a message is sent, the RESPOND field indicates the expected 
response— normal or exception (NEX) or exception only (EX)— and the source of 
the expected response— FME, RRN, or both FME and RRN. 

CONTROL= { DATA | QEC | RELQ | QC | CANCEL | CHASE | SHUTD | BID | LUS | SDT | 
CLEAR | STSN} (Record-mode only) 

Indicates the type of message to be sent to a terminal. With the exception of SDT, 
CLEAR, and STSN, all are used by the SEND macro instruction. SDT, CLEAR, and 
STSN are used by the SESSIONC macro instruction. See Chapter 5 of VTAM 
Concepts and Planning for an explanation of the indicators designated by 
CONTROL. 

CHAIN=FIRST | MIDDLE | LAST | ONLY (Record-mode only) 

This field is set when a message is sent to a terminal. It denotes the message's 
relative position within the chain currently being sent. ONLY means that the 
message is the sole element of the chain. 

CHNGDIR=(CMD |NCMD,RQ |NREQ) (Record-mode only) 

This field is set when a message or response is sent to a terminal. When CMD is set, 
a change-direction-command indicator is included in the message or response. When 
REQ is set, a change-direction-request indicator is included. 

BRACKET=(BB |NBB,EB |NEB) (Record-mode only) 

This field is set when a message is sent to a terminal. When BB is set, a 
begin-bracket indicator is included in the message. When EB is set, an end-bracket 
indicator is included. Note that both indicators can be included in one message. 

RTYPE=(DFSYN |NDFSYN,DFASY |NDFASY,RESP INRESP (Record-mode only) 

When a RECEIVE macro instruction is issued, the RTYPE field designates the type 
or types of input eligible to satisfy the macro instruction (only one type can 
actually satisfy the RECEIVE). When a SEND or RESETSR macro instruction is 
issued, the RTYPE field indicates the type or types of input for which the 
terminal's CA-CS mode is to be switched. 
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DFSYN 

designates synchronous flow messages. These include data messages and the QC, 
cancel, chase, bid, LUS, and RTR indicators. 

DFASY 

designates asynchronous flow messages. These include the QEC, RELQ, SHUTD, 
RSHUTD, SHUTC, and signal indicators. 

RESP 

designates responses. 

STYPE=REQ | RESP (Record-mode only) 

This field designates the type of output to be sent to a terminal. The application 
program uses STYPE=REQ to request that a message be sent. STYPE=RESP is used 
when a response is to be sent. STYPE=REQ must be set when a SESSIONC macro 
instruction is issued. 

SSENSEO=CPM | STATE |FI |RR (Record-mode only) 

This field is set when an exception response or logical-unit-status indicator is sent to 
a terminal. Its purpose is to tell the terminal the type of error that causes the 
exception condition to be raised. These error types are described in Appendix C. 

CPM 

designates a CPM error condition. 

STATE 

designates a STATE error condition. 

FI 

designates a Function Interpreter error condition. 

RR 

designates a Request Reject error condition. 

If this operand is omitted, the SSENSEO field is set to 0. 

Note: When an RPL is assembled or generated, and each time the RPL is reset to 
its inactive {that is, after each synchronous request or CHECK macro instruction), 
the SSENSEO field is cleared. 

SSENSMO=system sense modifier value (Record-mode only) 

This field is set when an exception response or a logical-unit -status indicator is sent 
to a terminal. The value set in this field is used in conjunction with the SSENSEO 
setting to describe the specific type of error that caused the exception condition to 
be raised. The meanings assigned to the SSENSMO values are described in Appendix 
C. If this operand is omitted, the SSENSMO field is set to 0. 

Format: Specify any decimal value that does not exceed 4096, specify a register 
(only the low-order byte is used), or specify a 1-byte hexadecimal or character 
constant. 

Examples: SSENSMO=l 
SSENSMO=l 
SSENSMO=(7) 
SSENSMO=S'FF 
SSENSMO=C'A' 
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Note: When an RPL is assembled or generated, and each time the RPL is reset to 
its inactive state (that is, after each synchronous request or CHECK macro 
instruction), the SSENSMO field is set to 0. 

USENSEO=user sense value (Record-mode only) 

This field is set when an exception response or logical-unit-status indicator is sent to 
a terminal. If this operand is omitted, the USENSEO field is set to 0. 

Format: Specify any decimal value that does not exceed 32,161, specify a register 
(only the low-order 2 bytes are used), or specify a 2-byte hexadecimal or character 
constant. 

Examples: USENSEO=13 
USENSEO=(7) 

usenseo=x,4f4f' 
usenseo=c;zz' 

Note: When the RPL is assembled or generated, and each time the RPL is reset to 
its inactive state (that is, after each synchronous request of CHECK macro 
instruction), the USENSEO field is set to 0. 

IBSQAC=SET|TESTSET | INVALID | IGNORE (Record-mode only) 
OBSQAC=SET | TESTSET | INVALID | IGNORE (Record-mode only) 

These fields are used by a SESSIONC macro instruction to designate which type of 
STSN indicator is being sent to a terminal. The setting of the IBSQAC field relates 
to the inbound sequence number; the OBSQAC field relates to the outbound 
sequence number. See the SESSIONC macro instruction for the responses that can 
be returned for each of the following: 

SET 

The sequence number is reset. The terminal is made aware of the number, but 
possible responses are limited. 

TESTSET 

The sequence number is reset. The logical unit is made aware of the number and 
returns a response regarding the validity of that number. 

INVALID 

The sequence number is not reset (the application program has lost its version of 
the sequence number). The terminal returns the sequence number. 

IGNORE 



The sequence number is not reset. No response is possible. 



IBSQVAL=inbound sequence number (Record-mode only) 
OBSQVAL=outbound sequence number (Record-mode only) 

When SESSIONC is used to send an STSN indicator and SET, TESTSET, or 
IGNORE is set in the IBSQAC or OBSQAC field, these fields contain the sequence 
number being reset or transmitted. 

Format: Specify any decimal value that does not exceed 65,535, or specify a 
register (only the low-order 2 bytes are used). 

OPTCD=option code | (option code,...) 

Indicates options that are to affect the connection and I/O requests made using this 
RPL. 
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Format: Code as indicated in the assembler format table. If only one option code 
is specified, the parentheses can be omitted. 

RPL ACB=ACB1 ,OPTCD=(SPEC,SYN,CS),AM=VTAM 
RPL ACB=ACBl,OPTCD=SPEC,AM=VTAM 

Note: The MODCB macro instruction can be used to change the option codes set 
in the RPL after it has been built. 

TRUNC | KEEP |NIBTK (Record-mode only) 

Indicates the action to be taken when a RECEIVE macro instruction is 
completed with input that is too large to fit in the input data area. TRUNC 
causes the excess data to be discarded. The application program is not notified 
that truncation occurred. KEEP causes the excess data to be saved for 
subsequent RECEIVE macro instructions. The application program can compare 
the value set in the RPL's RECLEN field (the amount of incoming data) with 
the value in the AREALEN field. If the RECLEN field is larger, excess data is 
present. NIBTK allows the TRUNC-KEEP processing option (see the NIB macro 
instruction) to determine whether excess data is to be kept or discarded. 

FMHDR INFMHDR (Record-mode only) 

This option code indicates to VTAM how the "formatted" bit in the Request 
Header (RH) of this data message is to be set. This option applies only to data 
messages (STYPE=REQ, CONTROL=DATA) and should be used to notify the 
terminal that the message contains or does not contain (FMHDR and NFMHDR, 
respectively) a user-defined Function Management Header. If FMHDR is set, the 
"formatted" bit is set on in the Request Header and is delivered to the receiver. 

CONANY|CONALL 

When an OPNDST macro instruction (with an ACQUIRE option) is issued and 
the NIB field of its RPL indicates a list of NIBs, this option code indicates the 
following: 

CONANY 

Connection is to be made to the first available terminal (if any) of the NIB 
list indicated by the NIB field. The request is completed when one 
connection has been made. 

CONALL 

Connection is to be made to all the available terminals in the list. The 
connections are made immediately. 

When a SIMLOGON macro instruction is issued and the NIB field of its RPL 
contains the address of a list of NIBs, this option code indicates the 
following: 

CONANY 

A simulated logon request is to be generated for the first available terminal of 
the NIB list. Control is passed to the application program's LOGON 
exit-routine, if one exists, when this one logon request has been generated. 
The parameter list passed to the LOGON exit-routine can be used to 
determine the identity of the terminal for which the logon request was 
generated. (See the EXLST macro instruction description.) The Q-NQ option 
applies. 
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CONALL 

Logon requests are to be generated for all the terminals represented in the 
NIB list. The SIMLOGON operation completes immediately. If Q is set, logon 
requests will be generated as each terminal becomes available. If NQ is set and 
all the terminals are available, the logon requests are generated immediately; 
if all are not available, however, no logon requests are generated. 

ACCEPT | ACQUIRE 

Indicates whether OPNDST is being issued to accept a terminal's logon request 
or whether it is being issued to acquire that terminal. 

ACCEPT 

VTAM connects the application program to a terminal that has issued a logon 
request. If the ANY option code is set and more than one terminal has issued 
a logon request and is waiting to be accepted, the first terminal that issued a 
logon request is connected. The symbolic name of that terminal is placed in 
the NIB pointed to by OPNDST's RPL. If the SPEC option code is in effect, 
the NIB must already contain the symbolic name of terminal: connection is 
established only if that particular terminal issues a logon request. 

ACQUIRE 

VTAM connects the application program to the terminal represented by this 
NIB if the terminal has not issued a logon request, and is available. The 
CONALL-CONANY option code determines which of the terminals repre- 
sented in the list (that have not issued logon requests) are connected. If 
CONALL is in effect, all of the available terminals represented in the list are 
connected. If CONANY is in effect instead, only the first available terminal 
represented in that list is connected. 

The use of ACQUIRE must be authorized for the application program by the 
installation. 

SPEC | ANY 

When the RPL is used by an OPNDST macro with an ACCEPT option code, 
these option codes indicate the following: 

SPEC 

Connection is to be made to a specific terminal if that terminal issues (or has 
issued) a logon request to the application program. The terminal is identified 
by placing its symbolic name in a NIB and placing the address of that NIB in 
the RPL's NIB field. 

ANY 

Connection is to be made to any terminal that has issued a logon request for 

the application program. 

When the RPL is used by a READ, SOLICIT, or RECEIVE macro instruction, 
these option codes indicate the following: 

SPEC 

Data is to be obtained from the specific terminal whose CID is in the RPL's 
ARG field. 

ANY 

For READ, data already obtained from any one terminal is to be moved to 

the application program's input area, subject to the setting of the terminal's 
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CS-CA option code. For SOLICIT, data is to be obtained from all of the 
terminals connected to the application program, subject to the setting of the 
CS-CA option code. For RECEIVE, data arriving from any one logical unit is 
to be moved to the application program's input area, subject to the setting of 
the logical unit's CS-CA option code and the RTYPE field of the RECEIVE 
macro instruction. 

QUIESCE | STOP | START 

Indicates how a SETLOGON request is to affect (1) the queuing of logon 
requests for a given ACB, and (2) the codes returned by INQUIRE 
(OPTCD=APPSTAT) issued by other application programs. This option code 
applies only if the ACB has been opened with MACRF= LOGON specified. 

QUIESCE 

No more logon requests can be directed at the ACB whose address is in the 
RPL's ACB field. Application programs issuing INQUIRE (OPTCD=APPST AT) 
for the application program will receive a return code indicating that the appli- 
cation program cannot accept logon requests, presumably because it is about 
to close the ACB. 

STOP 

Application programs issuing INQUIRE (OPTCD=APPSTAT) for the ACB 
receive a return code indicating that no logon requests should be directed at 
the ACB (but implying that logon requests will be accepted later). The use of 
this option, however, does not prevent logon requests from being queued if 
the other application programs ignore this indicator and issue CLSDST 
(OPTCD=PASS) anyway. SETLOGON (OPTCD=STOP) should be used to 
temporarily halt logon requests; use SETLOGON (OPTCD=QUIESCE) to 
permanently bar logon requests to the ACB. 

START 

Application programs issuing INQUIRE (OPTCD=APPSTAT) receive a return 
code indicating that the application program represented by the ACB is 
accepting logon requests. This version of SETLOGON also causes VTAM to 
commence queuing automatic logon requests if this is the first such 
SETLOGON request since the ACB was opened. SETLOGON 
(OPTCD=START) reverses the effect of a previous SETLOGON 
(OPTCD=STOP). 

PASS | RELEASE 

Indicates whether or not a logon request is to be generated when a CLSDST 
macro instruction is issued. 

PASS 

VTAM generates a simulated logon request on behalf of the terminal being 
disconnected and directs these requests to the application program whose 
symbolic name is pointed to by the RPL's AAREA field. If the RPL's 
AREALEN field contains a value other than 0, VTAM also send a logon 
message with the logon request. VTAM obtains the message from the storage 
area identified in the AREA field, and sends the number of bytes indicated in 
the AREALEN field. The use of CLSDST with PASS must be authorized by 
the installation. 

RELEASE 

No logon request is generated; the terminal is simply disconnected from the 
application program. 
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LOGONMSG | DEVCHAR | COUNTS | TERMS | APPSTAT | CIDXLATE | 
TOPLOGON|BSCID 

Indicates the action VTAM is to take when an INQUIRE macro instruction is 
issued. 

LOGONMSG 

INQUIRE retrieves the logon message of a terminal that has issued a logon 
request for the application program. 

The RPL's NIB field must point to a NIB whose NAME field contains the 
symbolic name of the terminal. The RPL's ACB field must indicate the ACB 
to which the logon request was directed. This information is provided in the 
parameter list passed to the LOGON exit-routine. 

The AREA and AREALEN fields must indicate the location and length of the 
storage area where the logon message is to be placed. 

DEVCHAR 

INQUIRE obtains the device characteristics of a terminal, as they are defined 
by the installation in the resource definition table at the time INQUIRE is 
executed. These device characteristics can be used by the application program 
to determine which processing options the program wants to set in the NIB 
used to connect the 

The RPL's ARG field must point to a NIB containing the symbolic name of 
the terminal, or the RPL's ARG field must contain the CID of the terminal. 
The device characteristics are placed in the program storage area whose 
location and length are indicated by the AREA and AREALEN fields of the 
RPL. See the INQUIRE macro instruction for details. 

COUNTS 

INQUIRE provides the number of terminals that are connected via a given 
ACB and the number of terminals that have requested logon via that ACB but 
have not yet been connected. These two numbers are placed in a four-byte 
area in program storage whose location and length are indicated by the AREA 
and AREALEN fields of the RPL. VTAM places the number of connected 
terminals in the first two bytes and the number of terminals requesting logon 
in the second two bytes. 

The connection and logon requests counted by INQUIRE are those directed 
to the ACB indicated by the ACB field. 

TERMS 

When this operand is specified, node initialization blocks (NIBs) are built by 
INQUIRE. 

The RPL's NIB field must point to a NIB whose NAME field contains the 
name of an entry that exists in the resource definition table at the time 
INQUIRE is issued. This entry must be a GROUP, LINE, CLUSTER, or 
TERMINAL entry that represents several terminals. A NIB is built for each 
terminal represented in the entry. 

Each generated NIB contains the symbolic name of the terminal. The flags for 
the LISTEND field are set to group the NIBs together into a NIB list. In addi- 
tion, device characteristics are supplied in the DEVCHAR field of each NIB. 
These characteristics can be used to reset the processing options of the NIB to 
values that are appropriate for the terminal. 
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The user must set each NIB's MODE field to BASIC before the NIBs are ready to be 
used for connection. 

APPSTAT 

This type of INQUIRE determines whether a given application program is 
available or unavailable. An available application is one whose ACB is active 
(open) and indicates that logon requests are to be accepted. 

The RPL's NIB field must point to a NIB whose NAME field contains the 
symbolic name of the application program whose status is being checked. A 
value returned in the RPL's FDBK field indicates whether the application 
program is available or not. See the INQUIRE macro instruction description 
for the codes that can be returned. 

CIDXLATE 

INQUIRE provides the symbolic name of the terminal whose CID you 
provide, or provides the CID of the terminal whose symbolic name you 
provide. 

If the RPL's ARG field contains the CID of the terminal, the eight-byte 
symbolic name of that terminal is returned in the data area indicated in the 
AREA field. If the RPL's NIB field contains the address of a NIB, the CID for 
the terminal whose symbolic name is in that NIB is placed in the RPL's ARG 
field. 

TOPLOGON 

For a given ACB, INQUIRE provides the symbolic name of the terminal that 
is currently at the top of the logon request queue for that ACB (that is, the 
terminal that has spent the greatest amount of time waiting for its logon 
request to be satisfied). 

The RPL's ACB field must indicate the ACB whose logon request queue is to 
be used. The eight-byte symbolic name of the terminal is returned in the data 
area indicated in the RPL's AREA field. 

BSCID 

INQUIRE returns the ID verification sequence of the terminal requesting 
logon. This form of INQUIRE is appropriate if the terminal's name (as 
provided in the LOGON exit-routine's parameter list) is one of the names 
established during VTAM definition as an unidentified terminal with an ID 
verification feature. 

The RPL's NIB field must point to a NIB whose NAME field contains the 
symbolic name provided in the LOGON parameter list. The sequence is 
placed in the work area defined by the AREA and AREALEN fields (set 
AREALEN to 20). 

SYN|ASY 

Indicates whether VTAM should synchronously or asychronously handle any 

request made using this RPL. 

SYN 

Synchronous handling means that when a request is made, control is not 
returned to the application program until the requested operation has been 
completed (successfully or otherwise). The application program should not 
use the CHECK macro instruction for synchronous requests; VTAM 
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automatically performs this checking (which includes clearing the ECB). 
When control is returned to the application program, registers and 1 5 will 
contain completion codes. 

ASY 

Asynchronous handling means that after VTAM schedules the requested 
operation, control is immediately passed back to the application program. 
When the event has been completed, VTAM does one of the following: 

• If the ECB address is specified for the RPL, VTAM posts a completion 
indicator in the event control block indicated by this operand. (If neither 
an ECB nor an EXIT address is specified in the RPL, the ECB field itself is 
used as an event control block.) The application program must issue a 
CHECK (or a system WAIT) macro to determine whether the ECB has 
been posted. 

• If the EXIT operand is in effect for the RPL, VTAM schedules the 
exit-routine indicated by this operand. This exit-routine should issue the 
CHECK macro so that the RPL can be reused, and also to cause automatic 
entry into a LERAD or SYNAD exit-routine if the requested operation 
ends with a logical or other error. CHECK should be issued in the 
exit-routine if the application program has no LERAD or SYNAD routine, 
since CHECK will return a code indicating whether or not a logical or 
other error occurred. 

Note: After an asynchronous request has been accepted and before that 
request has been completed, do not modify the RPL being used by the 
request This restriction also applies to a NIB during OPNDST processing. A 
modification during this interval could cause VTAM to be unable to complete 
the request in a normal manner, which in turn would cause VTAM to 
terminate the application program. 

CS|CA 

The CS (continue specific) and CA (continue any) option codes determine which 
type of input request is required to obtain data from the terminal. 

CS 

CS places the terminal into a status wherein only input requests that are 
directed specifically at the terminal can be used to obtain data from the 
terminal. These are the RECEIVE, READ, and SOLICIT macro instructions 
with OPTCD=SPEC specified. Looking at CS another way, it "immunizes" a 
terminal from input requests that are not specifically directed at the 
terminal— namely, RECEIVE, READ, or SOLICIT macro instructions issued 
in the any-mode. The status into which the terminal is placed is termed 
"continue-specific" mode. 

For example, while CS is in effect, the arrival of data from a logical unit that 
is in continue-specific mode does not trigger the completion of a RECEIVE 
(OPTCD=ANY) macro instruction that may have already been issued. 

CA 

CA places the terminal in a status wherein it's data is subject to RECEIVE or 
READ and SOLICIT macro instructions. This status is termed 
"continue-any" mode. 

Although the CS-CA option code affects only RECEIVE, SOLICIT, or READ 
operations, you can switch a terminal from one status to the other by 
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specifying the CS or CA option code in any OPNDST, SEND, RECEIVE, 
RESETSR, SOLICIT, READ, WRITE, or DO macro instruction. The change 
from one status to another is effective for the next I/O operation directed at 
the terminal, not when this macro instruction is executed. The terminal that 
is the object of the macro instruction is the one whose CS-CA status is 
changed. (For RECEIVE or READ with OPTCD=ANY, the terminal whose 
status will be changed is the one whose data is moved by the READ 
operation.) 

Continue-any and continue-specific modes can be set individually for a 
particular type of terminal input. For example, a terminal can be placed in 
continue-specific mode for synchronous flow messages while it is in 
continue-any mode for asynchronous flow messages and for responses. 

BLK | LBM | LBT (Basic-mode only) 

Indicates that the block of data to be transferred on a WRITE operation 
represents a block (BLK), the last block of a message (LBM), or the last block of 
a transmission (LBT). Appendix B shows the line control characters sent when 
each of these three option codes are in effect. BLK is invalid for a 3270 
Information Display System. 

CONV INCONV (Basic-mode only) 

Indicates whether or not a WRITE macro instruction is to be handled as a 
conversational write request. 

CONV 

Following the output operation, data is obtained from the terminal and 
placed in the area in program storage indicated by the RPL's AAREA field. 

NCONV 

Only the output operation is performed. 

COND | UNCOND | LOCK (Basic-mode only) 

Indicates the action to be taken when a RESET macro instruction is issued. 

COND 

RESET cancels any I/O operation that is pending for a specific terminal, but 
does not affect an I/O operation if data transfer has begun. This form of 
RESET cannot be used if an error lock is set. 

UNCOND 

RESET cancels any I/O operation with a specific terminal, whether or not 
data transfer has begun. Any data that has already been brought into VTAM 
buffers is kept by VTAM for subsequent retrieval by the application program 
(with a READ macro). Any data being sent or about to be sent by the 
terminal may be lost. RESET also resets any error lock that has been set for 
the terminal. 

LOCK 

RESET resets any error lock that has been set for the terminal. 

ERASE | E AU | NERASE (Basic-mode only) 

Indicates the action to be taken when a WRITE macro instruction is issued. 

ERASE 

WRITE erases the screen of a display device attached to a 3270 Information 
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Display System or a 2770 Data Communication System, and then sends a 
block of data to the device. 

EAU 

WRITE erases only the unprotected portion of the screen of a display device 
attached to a 3270 Information Display System. No data is written. 

NERASE 

WRITE performs an ordinary write operation with no display screen erasure. 
Use this option for all devices other than 3270 and 2770 devices. 

RELRQINRELRQ 

Indicates the action to be taken when a SIMLOGON macro is issued, and the 
terminal that is the object of this connection or simulated logon request is 
already connected to another application program— that is, already connected to 
an ACB other than the one being used for the SIMLOGON macro. 

RELRQ 

If the application program to which the terminal is connected has a RELREQ 
exit-routine, that routine is invoked. 

NRELRQ 

No RELREQ exit-routine is invoked. 

The effect of this option is to determine whether or not the owning 
application program is to be notified of your request. The NRELRQ option, 
for example, allows you to release a terminal to another application program, 
and then immediately request reconnection to assure its eventual return to 
your program. 

Note the difference in spelling between the RELRQ-NRELRQ RPL option, 
and the related exit-routine. The latter is coded in the EXLST macro 
instruction as RELREQ. 

QINQ 

Indicates the action VTAM is to take when the application program issues 
SIMLOGON or OPNDST (ACCEPT) and the terminal that is the object of this 
request is unavailable. 

Q 

VTAM is to schedule the LOGON exit-routine when the terminal is finally 
available and complete the OPNDST or SIMLOGON request when it has done 
so. For SIMLOGON, the RELRQ-NRELRQ option code determines if the 
application program to which the terminal is connected is notified of your 
request. 

NQ 

VTAM is to immediately return control to the application program. (Without 
the NQ option, a connection or simulated logon request might remain 
pending indefinitely, until another application program releases the terminal.) 



Also indicates the action VTAM is to take when the application program 
issues a RECEIVE macro instruction and no input that is eligible to satisfy 
the request is at that moment in VTAM's buffers. 
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VTAM is to satisfy the request when the input is finally available and 
complete the RECEIVE when it has done so. 

NQ 

VTAM is to terminate the request and return control to the application 
program immediately without performing any CA-CS mode switching. 



RPL Fields Set by VTAM 



Field Name 
ARECLEN 



RTNCD 



FDBK2 



FDBK 



SENSE 



REQ 



Content 

The number of bytes of data returned by the WRITE (OPTCD= 
CONV) and INTRPRET macro instructions. See WRITE and 
INTRPRET for details. 

A general return code returned by all of the RPL-based macro 
instructions. This is one of the feedback fields described in 
Appendix C. 

A specific error return code returned by all RPL-based macro 
instructions that are accepted by VTAM but are not completed 
successfully. This is one of the feedback fields described in 
Appendix C. A DSECT containing labeled EQU instructions for 
each FDBK2 return code is described in Appendix H 
(ISTUSFBC). These DSECT labels can be used instead of the 
numerical values that are cited for FDBK2 throughout this manual. 

Status information for INQUIRE, READ, or conversational 
WRITE macro instructions. For example, if the data ended with 
an EOM line-control character, this field is set to indicate this. 
This is one of the feedback fields described in Appendix C. 

The SENSE field contains status or sense bytes obtained from 
certain devices. The SENSE field applies only to DO, READ, and 
WRITE macro instructions, and is set following these macro 
instructions only if the RPL's FDBK2 field so indicates. There is 
more information about the SENSE field in Appendix C. 

A value returned by all RPL-based macro instructions except 
EXECRPL (and CHECK) that identifies the type of macro 
instruction. This field shows which type of macro instruction last 
used the RPL. These are the values that are set: 



Value 


Macro Instructk 


11(17) 


WRITE 


12(18) 


RESET 


13(19) 


DO 


15(21) 


SETLOGON 


16(22) 


SIMLOGON 


17(23) 


OPNDST 


19 (25) 


CHANGE 


1A(26) 


INQUIRE 


IB (27) 


INTRPRET 


ID (29) 


READ 


IE (30) 


SOLICIT 


IF (31) 


CLSDST 


22 (34) 


SEND 


23 (35) 


RECEIVE 


24 (36) 


RESETSR 


25 (37) 


SESSIONC 
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USER 



ARG 



AREA 



RECLEN 



Upon the completion of a SEND, RECEIVE, RESETSR, 
SESSIONC, READ, WRITE, SOLICIT, RESET, or DO macro 
instruction, this field contains whatever value you had previously 
placed in the USERFLD field of the NIB used to connect the 
terminal. See the description of the USERFLD operand of the 
NIB macro instruction for more information. 

A terminal's communication identifier (CID) provided by 
OPNDST. The CID is a 4-byte network-oriented version of the 
terminal's symbolic name. It is generated by VTAM when the 
terminal is connected to the application program, and is used by 
the application program to indicate identity of the terminals for 
subsequent I/O requests. More information about the CID and its 
use appears above in the description of the NIB operand of this 
macro instruction. 

The address of the NIB list supplies when an OPNDST (OPTCD= 
ACQUIRE) macro instruction is issued. This is the same address 
that the application program supplies in the NIB field (this type 
of OPNDST overlays the NIB address with a CID). 

After an INQUIRE macro instruction is completed RECLEN 
contains the length of the requested information (such as the 
logon message). AFTER a SETLOGON macro instruction is 
completed, RECLEN contains the number of logon requests 
already queued for the application program. After a READ or DO 
macro instruction is completed, RECLEN contains the amount of 
input data. After a RECEIVE, RECLEN contains the total length 
of available data. This value may be greater than AREALEN, 
indicating the presence of excess data (the value in RECLEN 
represents the total length of excess data plus the data in AREA). 



CONTROL After a RECEIVE macro instruction (RTYPE=DFSYN) is com- 

pleted, CONTROL is set to one of the following values: 



CONTROL=DATA 

CONTROL=QC 

CONTROL=CANCEL 

CONTROL=CHASE 

CONTROL=LUS 

CONTROL=RTR 



(data message received) 
(quiesce-completed indicator received) 
(cancel indicator received) 
(chase indicator received) 
(logical-unit-status indicator received) 
(ready-to-receive indicator received) 



After a RECEIVE macro instruction (RTYPE=DFASY) is com- 
pleted, CONTROL is set to one of the following values: 



CONTROL=QEC 

CONTROL=RELQ 
CONTROL=SHUTC 
CONTROL=RSHUTD 
CONTROL=SIGNAL 



(quiesce-at-end-of-chain indicator 

received) 

(release-quiesce indicator received) 

(shutdown indicator received) 

(shutdown-requested indicator received) 

(signal indicator received; check 

SIGDATA) 



SEQNO 



After a SCIP exit-routine is entered, the CONTROL field of the 
read-only RPL is set to one of the following values: 
CONTROL=RQR (request-recovery indicator received) 

When a SEND (POST=RESP) or a RECEIVE macro instruction 
has received a response, the SEQNO field contains the sequence 
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RPL 



RESPOND 



CHAIN 



CHNGDIR 



BRACKET 



RTYPE 



SSENSEI 



number of the message being responded to. When a SEND 
(POST=SCHED) is used to send a message (STYPE=REQ), the 
SEQNO field contains the VTAM-supplied sequence number of 
the message. 

When a SEND (POST=RESP) or a RECEIVE macro instruction 
has received a response, the RESPOND field indicates the type of 
response— normal (NEX) or exception (EX)— and the source of 
the response— FME, RRN, or both. When a RECEIVE macro 
instruction has received a message, the RESPOND field indicates 
the expected type of response— normal or exception (NEX) or 
exception only (EX)— and the expected source of the response— 
FME, RRN, of both. 

When a RECEIVE (RTYPE=DFSYN) macro instruction has 
received a message, the CHAIN field indicates the message's 
relative position within the chain. The possible settings are 
CHAIN=FIRST, CHAIN=MIDDLE, CHAIN=LAST, and 
CHAIN=ONLY. 

When a message or response is received, the CHNGDIR field 
indicates the presence of change-direction indicators. The possible 
CHNGDIR settings are: 



CHNGDIR=(NCMD,REQ) 
CHNGDIR=(CMD,NREQ) 
CHNGDIR=(NCMD,NREQ) 



(change-direction-request indicator 
present-DFASY or RESP only) 
(changed-direction command indi- 
cator present— DFSYN only) 
(neither indicator present) 



When a message is received, the BRACKET field indicates the 
presense of bracket indicators. The possible BRACKET settings 
are: 



BRACKET=(BB,EB) 

BRACKET=(NBB,EB) 
BRACKET=(BB,NBB) 
BRACKET=(NBB,NEB) 



(begin-bracket and end-bracket 
indicators both present) 
(end-bracket indicator present) 
(begin-bracket indicator present) 
(neither indicator present) 



When a RECEIVE macro instruction is completed, the RTYPE 
field indicates the type of input that caused the completion. The 
possible RTYPE field settings are: 

RTYPE=DFSYN (data or other synchronous flow 

message received) 
RTYPE=DFASY (asynchronous flow message received) 

RTYPE=RESP (response received) 

When a SEND (POST=RESP), RECEIVE, or SESSIONC macro 
instruction receives an exception message or response, the 
SSENSEI field indicates the presence of a system sense error 
code. These codes are described in Appendix C. Possible 
SSENSEI settings are: 



SSENSEI=PATH 

SSENSEI=CPM 

SSENSEI=STATE 

SSENSEI=FI 

SSENSEI=RR 

SSENSEI=0 



(Unrecoverable PATH error condition) 
(CPM error condition) 
(STATE error condition) 
(Function Interpreter error condition) 
(Request Reject error condition) 
(no system sense error code) 
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SSENSMI When a SEND (POST=RESP), RECEIVE, or SESSIONC macro 

instruction receives an exception message or response, the 
SSENSMI field indicates the presence of a system sense modifier 
value. The modifier values are described in Appendix C. The value 
is tested as a 1-byte quantity. If SHOWCB is used, the value is 
right-adjusted in the 4-byte work area; the other 3 bytes are set to 
0. 

USENSEI When a SEND (POST=RESP), RECEIVE, or SESSIONC macro 

instruction receives an exception message or response, the 
USENSEI field may contain a user sense value. This value is 
tested as a 2-byte quantity. If SHOWCB is used, the value is 
right-adjusted in the 4-byte work area; the other 2 bytes are set to 
0. 

SSENSEO This field is always set to when an RPL-based macro is 

completed. 

SSENSMO This field is always set to when an RPL-based macro is 

completed. 

USENSEO This field is always set to when an RPL-based macro is 

completed. 

IBSQAC When a SESSIONC macro instruction (CONTROL=STSN) is 

completed, the IBSQAC field contains the terminal's response 
regarding the inbound sequence number. Possible settings are 
TESTPOS, TESTNEG, INVALID, and RESET. See the 
SESSIONC macro instruction for more information. 

OBSQAC When a SESSION macro instruction (CONTROL=STSN) is 

completed, the OBSQAC field contains the terminal's response 
regarding the outbound sequence number. The possible settings 
for OBSQAC are the same as those for IBSQAC. 

IBSQVAL When a SESSIONC macro instruction (CONTROL=STSN) is 

completed and IBSQAC is set to TESTPOS or TESTNEG, the 
IBSQVAL field contains the terminal's version of the inbound 
sequence number. 

OBSQVAL When a SESSIONC macro instruction (CONTROL=STSN) is 

completed and OBSQAC is set TESTPOS or TESTNEG, the 
OBSQVAL field contains the terminal's version of the outbound 
sequence number. 

SIGDATA When a RECEIVE macro instruction receives a signal indicator 

(CONTROL=SIGNAL), the SIGDATA field contains the signal 
information sent by the terminal. The value in this field is tested 
as a 4-byte quantity. 



Examples 



RPL1 



RPL 



ACB= ACB 1 ,NIB=NIB 1 , AM=VT AM 

OPTCD=(SPEC,ASY), 

EXIT=EXITPGM 



RPL1 can be used by an OPNDST macro instruction to connect the terminal 

represented in NIB1 to the application program, that is, to ACB1. When the 

operation is completed, the application program will be interrupted, and the 
routine at EXITPGM is invoked. 



124 



RPL 



RPL2 RPL ACB=ACB1,AM=VTAM,AREA=S0URCE,P0ST=RESP, 

RECLEN=132,ECB=ECBWORD,OPTCD=ASY 

RPL2 can be used by a SEND macro instruction to write a data message (1 32 bytes 
from SOURCE) to a terminal. When the request has been accepted, control is 
returned. When the request has been completed, ECBWORD is posted. (The 
CHECK macro instruction used to check the write operation would point to 
RPL2.) 

RPL Fields and RPL-Based 

Macro Instructions Figure 9 shows all of the VTAM macro instructions that allow RPL modifications 

to be indicated when the macro instruction is coded. It also shows all of the RPL 
fields, including the option codes of the OPTCD field, that might be modified by 
the application program or by VTAM. The symbols in the table indicate, for a given 
macro instruction, the RPL fields that are set by VTAM or by the application 
program. 
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RPL— modifying macro instructions —i^ 
Applicable RPL fields: 
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Figure 9 (Part 1 of 2). The RPL Fields Applicable to the Macro Instructions That Can Modify RPLs 
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Applicable RPL fields (Cont.): 
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The presence of a symbol means that the RPL field or option code is applicable for the macro instruction 
in one of these two ways: 

The field or option code is set by the application program to supply VTAM information about 
the request. 



V I The field is set by VTAM when the request has been processed. 



Figure 9 (Part 2 of 2). The RPL Fields Applicable to the Macro Instructions That Can Modify RPLs 
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The SEND macro instruction is used in three major ways: 



Send A Data Message. 
STYPE=REQ, 
CONTROL=DATA 








Responded output: Response included as part of the 
SEND macro instruction. 
POST=RESP 










Scheduled output: SEND macro instruction completed as 
soon as output data area free; response 
(if any) obtained with a RECEIVE 
macro instruction. 
POST=SCHED 









Send a Nondata Message. 
STYPE=REQ, 
CONTROL^ 








QEC 


Send a quiesce-at-end-of-chain indicator. 




RELQ 


Send a release-quiesce indicator. 


QC 


Send a quiesce-completed indicator. 


CANCEL 


Send a cancel indicator. 


CHASE 


Send a chase indicator. 


BID 


Send a bid indicator. 


SHUTD 


Send a shutdown indicator. 


LUS 


Send a logical-unit-status indicator. 









Send a Response to a data message or to a cancel, chase, LUS, or QC indicator. 
STYPE=RESP,CONTROL=DATA|CANCEL (CHASE |LUS|QC* 





Normal Response 






Exception Response 




FME 


RRN 






FME 


RRN 




FME& RRN 


FME& RRN 















Note: RTR cannot be set by the application program; use the RPL that received the RTR indicator. 



Figure 10. The Major SEND Options 
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SEND-Send Output to Logical Unit 



The SEND macro instruction transmits a message or a response to a logical unit or 
to a record-mode 3270 terminal. 

The major options for a SEND macro instruction are illustrated in Figure 10. 

Two options are available when data or other synchronous flow messages are sent. 
The first, scheduled output, is completed as soon as the output data area containing 
the message can be reused. This occurs prior to the actual transmission of the 
message. The resulting response (if any) is received via a separate RECEIVE macro 
instruction or in a RESP exit-routine. The second option, responded output, is not 
completed until the record has been transmitted and a response is returned. The 
RPL used for the SEND macro instruction is used to describe the response; no 
separate RECEIVE macro instruction or RESP exit-routine is used. Responded 
output can be used only when a response is assured. 

The RESPLIM field of a terminal's NIB limits the number of concurrent responded 
output requests. Scheduled output requests cannot be stacked in this manner, 
however. Only one outstanding (uncompleted) scheduled output request is 
permitted at a time. 



Name 


Operation 


Operands 


[symbol] 


SEND 


RPL=rpl address 

[ , rpl field name=new value] ... 



RPL=rpl address 

Indicates the location of the RPL that describes the SEND operation. 

rpl field name=new value 

Indicates an RPL field to be modified, and the new value that is to be contained or 
represented within it. If you wish to avoid the possibility of program reassembly 
following future releases of VTAM, set the RPL field with MODCB macro 
instructions rather than with the SEND macro instruction. 

Format: For rpl field name code the keyword of the RPL macro instruction 
operand that corresponds to the RPL field being modified. The new value can be 
any value that is valid for that operand in the RPL macro instruction, or it can 
indicate a register. ARG=(register) can also be coded. 

Although any RPL operand can be specified, the following operands apply to the 
SEND macro instruction: 

ACB=acb address 

indicates the ACB that identifies the application program and was used when the 
target terminal was connected. 

ARG=(register) 

The SEND macro instruction is always directed at one specific terminal. The ARG 

operand specifies the register containing the CID of the terminal being written to. If 

the ARG field is not modified, the CID that is already in the RPL's ARG field is 

used. 
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AREA=output data address 

The data contained at the location designated by AREA is sent to the terminal. 
This storage can be reused as soon as VTAM has transferred the data to its own 
buffers (see POST=SCHED below). This operand is meaningful only if data is being 
sent (CONTROL=DATA). 

RECLEN=output data length 

The number of bytes of data indicated in this field is sent to the terminal. If the 
RECLEN field is set to 0, the AREA field is not examined. 

STYPE=REQ | RESP 

Designates whether a message (STYPE=REQ) or a response (STYPE=RESP) is to be 
sent. The CONTROL field governs the type of message sent, while the RESPOND 
field governs the type of response sent. 

CONTROL=DATA | QEC | RELQ | QC | CANCEL | CHASE | SHUTD | BID | LUS 

CONTROL=DATA 

Sends a data message. 

CONTROL=QEC 

Sends a quiesce-at-end-of-chain indicator. This informs the terminal that when it 
is through transmitting the current chainit is to stop transmitting and return a 
quiesce-completed (QC) indicator. 

CONTROL=RELQ 

Sends a release-quiesce indicator. This informs the terminal that it can begin 
transmitting messages. 

CONTROL=QC 

Sends a quiesce-completed indicator. This informs the terminal that the 
application program will no longer transmit data and is prepared to receive. Once 
this indicator is sent, no data can again be transmitted to the terminal until the 
terminal returns a release-quiesce (RELQ) indicator. 

CONTROL=CANCEL 

Sends a cancel indicator. The terminal interprets this signal as an indication that 
the terminal should discard the chain that it is receiving. A cancel indicator is 
sent instead of a CHAIN=LAST message when a message chain is canceled. 

CONTROL=CHASE 

Sends a chase indicator. When the application program receives a response to this 
indicator, it can be certain that no messages are in the network for which the 
terminal has failed to return a response. 

CONTROL=SHUTD 

Sends a shutdown indicator. The terminal interprets this as an indication that 
the application program is about to disconnect the terminal. When the terminal 
is ready to accept disconnection, it returns a shutdown-completed (SHUTC) 
indicator. 

CONTROL=BID 

Sends a bid indicator. Thei terminal interprets this as a request on the part of the 
application program for permission to begin a new bracket. 
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CONTROL=LUS 

Sends a logical-unit-status indicator. A logical-unit-status (LUS) indicator 
conveys exactly the same type of information as does an exception response. An 
LUS is sent when the application program wishes to raise an exception 
condition, but cannot do so with an exception response (for example, the 
terminal is sending messages and requesting no responses whatever). The 
SSENSEO, SSENSMO, and USENSEO fields are used for LUS indicators. 

BRACKET=(BB | NBB,EB | NEB) 

This field indicates whether the message forms the beginning, middle, end, or sole 
element of a bracket. This operand is meaningful only when brackets are being used 
by the terminal (see VTAM Concepts and Planning for an explanation of brackets). 

BRACKET=(BB,NEB) 

This is the beginning of a bracket. 

BRACKET=(NBB,NEB) 

This is the middle of a bracket. 

BRACKET=(NBB,EB) 

This is the end of a bracket. 

BRACKET=(BB,EB) 

This message is a bracket. 

CHNGDIR=(CMD |NCMD,REQ |NREQ) 

This operand indicates the type of change-direction indicator to be sent (see VTAM 
Concepts and Planning for an explanation of change-direction indicators): 

CHNGDIR=(CMD,NREQ) 

Send a change-direction-command indicator (valid only for DFSYN). 

CHNGDIR=(NCMD,REQ) 

Send a change-direction-request indicator (valid only for RESP and DFASY). 

CHNGDIR=(NCMD,NREQ) 

Send no change-direction indicator. 

CHAIN=FIRST | MIDDLE | LAST |ONLY 

Indicates the position of the message within the chain currently being transmitted. 

BRANCH=YES |NO 

If SEND is being issued in an application program that is running in privileged state 
under a TCB (OS/VS2 only), BRANCH can be set to YES. See the RPL macro 
instruction for more information. 

POST=SCHED|RESP 

This operand defines at what point in the output operation the SEND macro 
instruction is to be completed. (The OPTCD=SYN | ASY, ECB, and EXIT 
parameters govern the action to be taken when the macro instruction is completed.) 
The POST operand applies only to the transmission of data messages. 

POST=SCHED (scheduled output) 

Indicates that the macro instruction is to be completed as soon as the output 
data area (pointed to by the AREA field) and the RPL are available for reuse. 
This occurs prior to the actual transmission of the data from the CPU. A 
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RECEIVE macro instruction (or a RESP exit-routine) is required to obtain the 
response. Only one SEND with POST=SCHED can be outstanding for a given 
terminal at one time. A second SEND with POST=SCHED issued before the first 
has been completed is rejected by VTAM with a logical error return code. 
POST=SCHED is assumed if the RESPOND field indicates that no response (or 
only an exception response) is expected— that is, if a response is not assured. 

POST=RESP (responded output) 

Indicates that the macro instruction is to be completed when a response unit is 
returned from the terminal. No separate RECEIVE is used to obtain the 
message's response; the response information is posted in the SEND RPL. The 
RESPLIM field of the terminal's NIB limits the number of SEND macro 
instructions with POST=RESP that can be outstanding at one time. POST=RESP 
can only be used when a response is assured— that is, when the RESPOND field 
of the SEND RPL is set to NEX. If EX is used for RESPOND, POST=SCHED is 
assumed by VTAM (the actual setting of the POST field is ignored). 

When a response is being sent by the application program (STYPE=RESP) 
posting takes place as though POST=SCHED had been specified (the actual 
setting of the POST field is ignored). The limit of one SEND (POST=SCHED) 
outstanding for a terminal at a time does not apply to the sending of responses. 

When a non-data message is sent (STYPE=REQ, CONTROL set to other than 
DATA), posting takes place as though POST=RESP had been specified; the 
actual setting of the POST field is ignored. 

ECB | EXIT=ecb or rpl exit-routine address 

Indicates the action to be taken by VTAM when an asynchronous (OPTCD=ASY) 
SEND macro instruction is completed. The actual or implied setting of the POST 
field governs what constitutes the "completion" of the SEND macro instruction. If 
EXIT is specified, the RPL exit-routine is scheduled. Otherwise, the ECB is posted 
and CHECK or WAIT must be used to determine when posting occurs. See the RPL 
macro instruction for more information. 

OPTCD=SYN|ASY 

When SYN is set, control is returned to the application program when the SEND 
operation is completed (see the POST operand above). When ASY is set, control is 
returned as soon as VTAM has accepted the SEND request. Once the operation has 
been completed, the ECB is posted or the RPL exit-routine is scheduled, as 
indicated by the ECB-EXIT field. See the RPL macro instruction for more 
information. 

OPTCD=CA|CS 

When the SEND operation is completed, the terminal is placed in continue-any 
mode (OPTCD=CA) or continue-specific mode (OPTCD=CS). 

The switch of continue-any and continue-specific modes applies to the type of 
input specified by the RTYPE field. More than one type of input can be specified. 
VTAM will attempt to switch the modes for all specified types of input. No 
switching occurs if RTYPE=(NDFSYN,NDFASY,NRESP) is in effect for the 
SEND. 

OPTCD=FMHDR |NFMHDR 

When OPTCD=FMHDR is used, the receiver is notified that the data contains a 
user-defined header ("Function Management Header"). 
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SEQNO=sequence number 

This field is set by the application program only when a response is being sent 
(STYPE=RESP). The sequence number must be the same as the sequence number 
of the "oldest" message to which a response is required but to which you have not 
yet responded. (Note— if the RPL used to receive a message is used to send the 
response, the SEQNO field will already be set to the correct value.) 

RESPOND=(EX |NEX,FME |NFME,RRN |NRRN) 

When a message is being sent (STYPE=REQ), this field indicates the requested 

response: 

RESPOND=EX,FME,RRN 

Only exception FME and RRN responses expected (see note below). 

RESPOND=EX,FME,NRRN 

Only exception FME response expected. 

RESPOND=EX,NFME,RRN 

Only exception RRN response expected. 

RESPOND=EX,NFME,NRRN 

No response expected. 

RESPOND =NEX,FME,RRN 

Normal or exception FME and RRN responses expected (see note below). 

RESPOND=NEX,FME,NRRN 

Normal or exception FME response expected. 

RESP OND=NEX,NFME ,RRN 

Normal or exception RRN response expected. 

RESPOND=NEX,NFME,NRRN 

No response expected. 

Note: When both FME and RRN responses are returned and POST=RESP for 
the SEND RPL, the first response completes the SEND request. If the two 
responses are returned together, both are received as one response- that is, the 
second response is also reflected in the completed RPL. If the second response 
does not accompany the first, however, the second response must be received by 
a separate RECEIVE macro instruction or by a RESP exit-routine. 

When a response is being sent (STYPE=RESP), this field indicates the response 
type: 

RESPOND=EX,FME,RRN 

This is an exception FME and RRN response. 

RESPOND=EX,FME,NRRN 

This is an exception FME response. 

RESPOND=EX,NFME,RRN 

This is an exception RRN response. 

RESPOND=EX,NFME,NRRN 

Invalid. 
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RESPOND=NEX,FME,RRN 

This is a normal FME and RRN response 

RESPOND=NEX,FME,NRRN 

This is a normal FME response. 

RESPOND=NEX,NFME,RRN 

This is a normal RRN response. 

RESPOND=NEX,NFME,NRRN 

Invalid. 

SSENSEO=PATH | CPM | STATE | FI | RR 

This field contains the system sense code that is to be sent to theterminallas part of 
an exception response or logical-unit-status (LUS) indicator. The system sense code 
represents a major class of error and is used in conjunction with the; SSENSMO 
(system sense modifier value) to describe a specific type of error. There is more 
information about the SSENSEO and SSENSMO fields near the end of Appendix C. 

Note: When an RPL is assembled or generated, and each time the RPL is reset to 
its inactive (that is, after each synchronous request or CHECK macro instruction), 
the SSENSEO field is cleared. 

SSENSMO=system sense modifier value 

This field, in conjunction with the code in the SSENSEO field, defines a particular 
type of network-defined error. The type of error represented by each system sense 
modifier value is described near the end of Appendix C. Like SSENSEO, SSENSMO 
is meaningful only when an exception response or a logical-unit-status (LUS) 
indicator is sent to the terminal. The system sense modifier value is coded as a 
decimal quantity (maximum of 4096) or as any 1-byte framed hexadecimal or 
character constant (such as SSENSMO=X'FF' or SSENSMO=C'A'). Register 
notation can also be used. 

Note: When an RPL is assembled or generated, and each time the RPL is reset to 
its inactive state (that is, after each synchronous request or CHECK macro 
instruction), the SSENSMO field is set to 0. 

USENSEO=user sense value 

The value set in this field is sent to the terminal as part of an exception response or 
as part of a logical-unit-status (LUS) indicator. It is used to tell the terminal that 
the exception condition is not being raised because of a network-related error 
(SSENSEO and SSENSMO) but because of an application-related error. The 
meaning attached to the value set in the USENSEO field is defined by the logic in 
the application program and in the customer-coded portion of the terminal,not by 
IBM. The user sense value is coded as any 2-byte decimal quantity or as any 
two-byte framed hexadecimal or character constant (such as USENSEO=X'4F4F', 
or USENSEO=C'ZZ'). Register notation can also be used. 

Note: When the RPL is assembled or generated, and each time the RPL is reset to 
its inactive state (that is, after each synchronous request on CHECK macro 
instruction), the USENSEO field is set to 0. 

Example SEND1 SEND RPL=RPLl,STYPE=REQ,CONTROL=DATA, 

AREA=OUTBUF,RECLEN=60,CHAIN=O NLY, 
POST=SCHED,RESPOND=(EX,FME,NRRN) 
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SEND1 sends a 60-byte data message to the terminal identified in RPLl's ARG 
field. SEND1 is completed as soon as VTAM has scheduled the output operation 
and OUTBUF (and RPL1) are available for reuse. The RESPOND field indicates 
that only an exception FME response should be returned; that is, if the message 
arrives normally, , no. response is to be returned. A separate RECEIVE (or RESP 
exit-routine) iSj required. to obtain the exception response, if one is returned. 

Return of Status Information After the SEND operation is completed, the following RPL fields are set: 

The sequence number is placed in the SEQNO field. 

The USER field contains the value that was set in the USERFLD field of the 
NIB when the terminal was connected. 

If POST=RESP and an exception response has been returned, the SSENSEI field 
may contain a system sense error code. The values that can be set in the 
SSENSEI field are the same as those that can be set in the SSENSEO field- 
namely, CPM, STATE, FI, or RR. In addition, PATH can be set when an 
unrecoverable PATH error has occurred. There is more information about these 
codes near the end of Appendix C. 

If POST=RESP and an exception response has been returned, the SSENSMI field 
may contain a system sense modifier value. This field is tested- as a quantity 1 
byte in length. There is more information about the SSENSMI codes near the 
end of Appendix C. 

If POST=RESP and an exception response has been returned, the USENSEI field 
may contain a user sense value. This field is tested as a quantity two bytes in 
length. 

The value 34 (decimal) is set in the REQ field, indicating a SEND request. 

The RTNCD and FDBK2 fields are set as indicated in Appendix C. Registers 
and 15 are also set as indicated in Appendix C. 

In addition to the above fields, the following fields may be set when a response has 
been received (POST=RESP): 

The CHNGDIR field indicates whether a change-direction-command or change- 
direction-request indicator is present as part of the response. 

The RESPOND field indicates the type of response unit that has been returned. 
This field is set in exactly the same manner as indicated above for sending a 
response unit. 
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SESSIONC-Send an SDT, Clear, or STSN indicator to a Logical Unit (Record Mode only) 

SESSIONC sends start-data-traffic (SDT), clear, and set-and-test-sequence-number 
(STSN) indicators to a specific logical unit (Figure 11). 

The effect of an SDT indicator is to permit the application program to send to the 
terminal and to permit the terminal to send to the application program. 

The effect of a clear indicator is to immediately stop the flow of all messages and 
responses between the terminal and the application program. All pending I/O 
requests for the terminal are canceled and all incoming and outgoing messages and 
responses that have not yet been received are discarded. 



SESSIONC is used in one of three major ways: 



Send a Start-data-traffic indicatior to a logical unit. 
1 CONTROL=SDT 

Allows the flow of messages and responses to begin (or resume) 



Send a Clear indicatior to a logical unit. 

2 CONTROL=CLEAR 

Prevents the flow of messages and responses (but not other SESSIONC indicators). Neither 
the application program nor the logical unit can send. All pending SEND, RECEIVE, and 
RESETSR macro instructions are cancelled with a physical error return code. 



Send a Set-and-test-sequence number indicator to a logical unit. 
3 CONTROL=STSN 

Setting of I BSQAL 

or OBSQAC Field Purpose 






SET 


Reset the sequence number and also 
send it to the logical unit. 




TESTSET 


Reset the sequence number, send it to the 
logical unit, and obtain reply. 


INVALID 


Obtain the sequence number from the 
logical unit. 


IGNORE 


Send the sequence number to the 
logical unit, but do not reset the 
sequence number. 







Figure 1 1. The Major SESSIONC Options 



136 



SESSIONC 



When the application program and the terminal discover that their inbound or 
outbound sequence numbers are different, the application program uses STSN 
indicators to communicate with the terminal. The purpose is to establish the 
correct sequence number while traffic flow is suspended. STSN indicators are used 
in conjunction with SDT and clear indicators as described in VTAM Concepts and 
Planning. 

There are four STSN indicators that the application program can send to the 
terminal: SET, TESTSET, INVALID, and IGNORE. The effects of these STSN 
indicators are discussed below under the IBSQAC and OBSQAC operand 
descriptions. 

A SESSIONC macro instruction can be used to send STSN indicators that apply to 
either the inbound or the outbound sequence numbers, or that apply to both 
independently. 

When SDT, clear, and STSN indicators are sent to the terminal, a normal or 
exception FME response is returned as part of the SESSIONC operation. That is, 
the indicator is sent as though POST=RESP and RESPOND=(NEX,FME,NRRN) 
had been specified on a SEND macro instruction. If an exception response is 
returned, the SSENSEI, SSENSMI, and USENSEI fields are set as they would be for 
any other type of response. 



Name 


Operation 


Operands 


[symbol] 


SESSIONC 


RPL=rpl address 

[ , rpl field name=new value] ... 



RPL=rpl address 

Indicates the location of the RPL that describes the SESSIONC operation. 

rpl field name=new value 

Indicates an RPL field to be modified and the new value that is to be contained or 
represented within it. If you wish to avoid the possibility of program reassembly 
following future releases of VTAM, set the RPL field with MODCB macro 
instructions rather than with the SESSIONC macro instruction. 

Format: For rpl field name code the keyword of the RPL macro instruction 
operand that corresponds to the RPL field being modified. ARG can also be coded. 
The new value can be any value that is valid for that operand in the RPL macro 
instruction, or it can indicate a register. Register notation must be used if ARG is 
used. Although any RPL operand can be specified, the following apply to a 
SESSIONC macro instruction: 

ACB=acb address 

Indicates the ACB that identifies the application program and was used when the 
terminal was connected. 

ARG=(register) 

The SESSIONC macro instruction is always directed at one specific terminal. The 
ARG operand specifies the register containing the CID of that terminal. If the ARG 
field is not modified, the CID already in the RPL's ARG field is used. 
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ECB | EXIT=ecb or rpl exit-routine address 

Indicates the action to be taken by VTAM when an asynchronous (OPTCD=ASY) 
SESSIONC request is completed. A SESSIONC request is completed when the 
SESSIONC indicator has been sent to the terminal and a response to it has been 
returned and posted in the RPL (similar to a SEND request with POST=RESP). If 
EXIT is specified, the RPL exit-routine is scheduled. Otherwise, the ECB is posted 
and CHECK or WAIT must be used to determine when the posting occurs. See the 
RPL macro instruction for more information. 

OPTCD=SYN|ASY 

When SYN is set, control is returned to the application program when the 
SESSIONC request is completed (the request is completed when the indicator has 
been sent and a response has been returned). When ASY is set, control is returned 
as soon as VTAM has accepted the SESSIONC request; once the requested 
operation has been completed, the ECB is posted or the RPL exit-routine is 
scheduled as indicated by the ECB-EXIT field. See the RPL macro instruction for 
more information. 

CONTROL=SDT | CLEAR | STSN 

CONTROL=SDT 

Sends a start-data-traffic indicator to the terminal. The effect of this indicator is 
to allow the flow of messages and responses to begin (or to resume, if a clear 
indicator has been issued to stop the flow). When SDT=SYSTEM is coded as part 
of the terminal's NIB, VTAM automatically sends a start-data-traffic indicator as 
part of the connection process. If SDT=APPL is coded instead, it is the 
application program's responsibility to send the indicator when data traffic is to 
begin. 

CONTROL=CLEAR 

Sends a clear indicator to the terminal. The effect of this indicator is to stop the 
flow of messages and responses and to discard data that is still in the network. 
All SEND, RECEIVE, RESETSR, and SESSIONC requests in progress are 
completed normally or with RTNCD=12 and FDBK2=12 (SYN AD entered). All 
subsequent SEND and RESETSR requests will be rejected with a RTNCD=20 
and FDBK2=65 (LERAD entered). 

CONTROL=STSN 

Sends a set-and-test-sequence-number indicator to the terminal. The effect of the 
STSN indicator depends on its type (as specified in the IBSQAC and OBSQAC 
fields) and the sequence number sent with it (as specified in the IBSQVAL and 
OBSQVAL fields). 

IBSQVAL=inbound sequence number 

Indicates a value that is 1 less than the new value that VTAM is to begin assigning 
to inbound messages. The application program sets this field only if SET or 
TESTSET is also specified in the IBSQAC field. The IBSQVAL field may be 
modified by the STSN response. 

OBSQVAL=outbound sequence number 

Indicates a value that is 1 less than the new value that VTAM is to begin assigning 
to outbound messages. The application program sets this field only if SET or 
TESTSET is also specified in the OBSQAC field. The OBSQVAL field may be 
modified by the STSN response. 
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IBSQAC=SET | TESTSET | INVALID | IGNORE 
OBSQAC=SET | TESTSET | INVALID | IGNORE 

The IBSQAC (inbound sequence number action code) and the OBSQAC (outbound 
sequence number action code) fields designate the type of STSN indicator sent to 
the terminal. The application program can set either or both of these fields. The 
effect of setting one is identical to the effect of setting the other, except that one 
applies to incoming messages and the other to outgoing messages. Figure 12 
summarizes the STSN indicator types and the responses they can elicit from the 
terminal. 

SET 

Sets the inbound or outbound sequence number to the value specified in the 
IBSQVAL or OBSQVAL field. When SESSIONC is completed, the IBSQAC or 
OBSQAC field contains the terminal's response to the new value: TESTPOS 
(agree) or RESET (set the sequence number again). 

TESTSET 

Sets the inbound or outbound sequence number as does SET, but a wider range 
of responses to the new value are possible: TESTPOS (agree), TESTNEG 
(disagree), INVALID (don't know) or RESET (set the sequence number again). 

INVALID 

Is used to obtain the terminal's version of the appropriate sequence number. 
Unlike SET and TESTSET, INVALID does not set the sequence number 
(INVALID is used when the application program has lost its version of the 
sequence number). The terminal can reply to this type of STSN indicator in 
three ways: TESTNEG (my version enclosed), INVALID (don't know either), or 
RESET (set the sequence number). 

IGNORE 

Is used to send a sequence number to the terminal without setting the sequence 
number. The terminal does not return any action code. 



Example 



SESSC1 SESSIONC 



Return of Status Information 



RPL=RPLl,CONTROL=STSN,OBSQAC=TESTSET 
OBSQVAL=(3),IBSQAC=IGNORE 



SESSC1 sends an STSN indicator to a terminal and sets the VTAM-supplied 
outbound sequence number to the value contained in register 3. The terminal, 
noting that the type of STSN indicator is TESTSET, can indicate TESTPOS, 
TESTNEG, INVALID, or RESET with its response. The response information is 
available in RPL1 when SESSC1 is completed. If OBSQAC is found by the 
application program to be set to TESTPOS or TESTNEG, the OBSQVAL field 
contains the terminal's version of the outbound sequence number. 

After the SESSIONC operation is completed, the following RPL fields are set: 

The value 37 (decimal) is set in the REQ field, indicating a SESSIONC request. 

The value originally set in the USERFLD field of the NIB is set in the USER 
field of the RPL. 

The IBSQAC and/or OBSQAC fields are set to TESTPOS, TESTNEG, INVALID, 
or RESET depending on the codes initially set in these fields when SESSIONC 
was issued. Figure 12 lists the codes that can be returned for each code initially 
set. 
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Value of the IBSQAC or OBSQAC field 
when SESSIONC issued 


Possible IBSQAC or OBSQAC field 
setting when SESSIONC completed 


SET 


Sequence number reset to value in 
IBSQVAL or OBSQVAL field. 


TESTPOS 
RESET 


Terminal agrees with value. Value 
returned in IBSQVAL or OBSQVAL 
field. 

Terminal requests another STSN 
indicator. No value returned. 


TESTSET 


Sequence number reset to value in 
IBSQVAL or OBSQVAL field. 


TESTPOS 

TESTNEG 

INVALID 
RESET 


Terminal agrees with value. Value 
returned in IBSQVAL or OBSQVAL 
field. 

Terminal disagrees with value. 
Terminal's version returned in 
IBSQVAL or OBSQVAL field. 

Terminal does not know the value. 
No value returned. 

Terminal requests another STSN 
indicator. No value returned. 


INVALID 


Application program does not know 
the sequence number value. 


TESTNEG 

INVALID 
RESET 


Terminal knows the value. Value 
returned in IBSQVAL or OBSQVAL 
field. 

Terminal doesn't know the value 
either. No value returned. 

Terminal requests another STAN 
indicator. No value returned. 


IGNORE 


Application program is sending a 
sequence number (as set in the 
INSQVAL or OBSQVAL field) 
without resetting the number. 


None 


Terminal receives the sequence 
number value but returns no 
IBSQAC or OBSQAC code and no 
IBSQVAL or OBSQVAL value. 



Figure 12. Types of STSN Indicators and Their Possible Responses 



The IBSQVAL and/or OBSQVAL fields contain a sequence number when the 
IBSQAC and/or OBSQAC field is set to TESTPOS or TESTNEG. See Figure 12. 

If an exception response is returned, the SSENSEI field may contain a system 
sense code. The possible codes (PATH, CPM, STATE, FI, or RR) are described 
near the end of Appendix C. 

If an exception response is returned, the SSENSMI field may contain a system 
sense modifier value. This value, combined with the system sense code contained 
in the SSENSEI field, describes the specific type of error that causes the 
exception condition to be raised. See Appendix C. This value is tested as a 
1-byte quantity. 

If an exception response is returned, the USENSEI field may contain a user 
sense value. This value is tested as a 2-byte quantity. 

The RTNCD and FDBK2 fields are set as indicated in Appendix C. 

Registers and 15 are also set as indicated in Appendix C. 
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SETLOGON-Reset an ACB's Logon Status 



There are three types of SETLOGON requests: QUIESCE, START, and STOP. The 
QUIESCE-ST ART-STOP option code in SETLOGON's RPL determines which type 
is used. None of these three versions has any effect unless the ACB was opened with 
MACRF=LOGON set. 

The START version of SETLOGON causes any application program issuing 
INQUIRE (OPTCD=APPSTAT) to receive a return code indicating that your 
application program is accepting logon requests. The first SETLOGON (OPTCD= 
START) issued after OPEN causes VTAM to begin scheduling the LOGON 
exit-routine for all automatic logon requests, for all new logon requests, and for any 
logon requests already queued. SETLOGON (OPTCD=START) reverses the effect 
of SETLOGON (OPTCD=STOP), but it does not reverse the effect of SETLOGON 
(OPTCD=QUIESCE). 

The STOP version of SETLOGON does not close the logon request queue; any 
CLSDST-initiated logon requests from other application programs cause the 
LOGON exit-routine to be scheduled. However, any application program issuing 
INQUIRE (OPTCD=APPSTAT) for your ACB receives a return code indicating that 
logon requests should not be directed at the ACB. 

The QUIESCE version of SETLOGON causes VTAM to prevent logon request 
queuing. There is no way to reopen the logon request queue short of closing the 
ACB and then reopening it. An application program might want to use this type of 
SETLOGON at the end of a day's work, prior to closing the ACB; this would give 
the application program a chance to handle its current load of logon requests 
without receiving new ones. Any application program issuing INQUIRE (OPTCD= 
APPSTAT) for your ACB will receive a return code indicating that your application 
program is shutting down and cannot receive logon requests. 

The STOP and QUIESCE versions of SETLOGON do not prevent the queuing of 
logon request that originates from logical units. 



To summarize: 



OPEN 



OPEN 



SETLOGON 



Request 

ACB's MACRF 

field set 
to NLOGON 



ACB's MACRF 
field set 
to LOGON 

RPL=RPL1, 
OPTCD=START 



Result 

No logon request of any kind can cause 
the LOGON exit-routine to be scheduled. 
SETLOGON cannot be used to permit 
LOGON exit list routine scheduling; only 
closing the ACB and reopening it with 
MACRF=LOGON will permit this. 

LOGON exit-routine scheduling can be 
started by a subsequent SETLOGON 
(OPTCD=START) 

LOGON exit-routine scheduling begins 
for all queued, new, and automatic logon 
requests. If a LOGON exit-routine is 
available, each logon request causes it to 
be scheduled. If a routine is not available, 
the request is queued awaiting an 
OPNDST (OPTCD=ANY) macro 
instruction. 
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SETLOGON 



RPL=RPL1, 
OPTCD=STOP 



SETLOGON 



RPL=RPL1, 
OPTCD=QUIESCE 



Does not stop the scheduling of the 
LOGON exit-routine, but causes applica- 
tion programs issuing INQUIRE 
(OPTCD=APPSTAT) to receive a return 
code indicating that logon requests 
should not be issued for your application 
program. 

Logon request permanently closed; it can 
be reopened only by closing and reopen- 
ing the ACB. Serves to notify other 
application programs issuing INQUIRE 
that logon requests cannot be accepted. 



Name 


Operation 


Operands 


[symbol] 


SETLOGON 


RPL=rpl address 

[ , rpl field name=new value] ... 



RPL=rpl address 

Indicates the location of the RPL that in turn indicates the ACB whose logon status 
is to be changed. 

rpl field name=new value 

Indicates an RPL field to be modified, and the new value that is to be contained or 
represented within it. If you wish to avoid the possibility of program reassembly 
following future releases of VTAM, set the RPL field with MODCB macro 
instructions rather than with the SETLOGON macro instruction. 

Format: For rpl field name code the keyword of the RPL macro instruction 
operand that corresponds to the RPL field being modified. The new value can be 
any value that is valid for that operand in the RPL macro instruction, or it can 
indicate a register. 

Although any RPL operand can be specified, the following operands apply to a 
SETLOGON macro instruction: 

ACB=acb address 

Indicates the ACB that identifies the application program whose logon queuing 
status is being changed. 

ECB | EXIT=ecb or rpl exit-routine address 

Indicates the action to be taken by VTAM when an asynchronous (OPTCD=ASY) 
SETLOGON macro instruction is completed. The macro instruction is completed 
immediately, subject to delays due to possible storage shortages. If EXIT is 
specified, the RPL exit-routine is scheduled. Otherwise, the ECB is posted, and 
CHECK or WAIT must be used to determine when posting occurs. See the RPL 
macro instruction for more information. 

OPTCD=SYN|ASY 

When SYN is set, control is returned to the application program immediately, 
subject to possible delays due to storage shortages. When ASY is set, control is 
immediately returned to the application program, regardless of possible delays in 
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the completion of the macro instruction When the macro instruction is completed, 
the ECB is posted or the RPL exit-routine is scheduled, as indicated by the 
ECB-EXIT field. 

OPTCD=QUIESCE | START | STOP 

When QUIESCE is set, no more logon requests can be queued for your application 
program. When START is used, the scheduling of the LOGON exit-routine begins 
for all new, queued, and automatic logon requests. When STOP is used, users of 
INQUIRE (OPTCD=APPSTAT) receive a return code indicating that logon requests 
should not be directed at your application program. If logon requests are directed 
at your application program nonetheless, VTAM will accept them and queue them 
for an eventual OPNDST. 



Example 



BEGIN 



OPEN ACB1 

SETLOGON RPL=RPL1 ,ACB=ACB 1 ,OPTCD=START 



TOOM AN Y SETLOGON RPL=RPL 1 , ACB= ACB 1 ,OPTCD=STOP 



RESUME SETLOGON RPL=RPL1,ACB=ACB1,0PTCD=START 



NOMORE SETLOGON RPL=RPL1,ACB=ACB1,0PTCD=QUIESCE 



ACB1 ACB 


APPLID=APPLNAME,MACRF=LOGON 


APPLNAME DC 


'05' 


DC 


CL5'STOCK' 



Before BEGIN is executed, the application program's LOGON exit-routine cannot 
be scheduled. Once BEGIN has completed however, STOCK's LOGON exit-routine 
is scheduled as each logon request occurs. (If the installation has defined a number 
of automatic logon requests, they will each cause the LOGON exit to be scheduled 
in turn.) 

TOOMANY causes VTAM to flag the application program as temporarily unwilling 
to accept logon requests. It does not prevent logon requests from being queued for 
STOCK. If an application program that wants to direct a logon request at ACB1 
first issues INQUIRE (OPTCD=APPSTAT), it will receive a return code indicating 
that logon requests should not be issued for STOCK. The IBM-supplied network 
solicitor program always issues this type of INQUIRE and honors the flag set by 
TOOMANY. 

RESUME reverses the effect of NOMORE; application programs issuing INQUIRE 
(OPTCD=APPSTAT) will receive a return code indicating that logon requests are 
being accepted (the same return code that results if INQUIRE is issued after BEGIN 
but before TOOMANY). 

NOMORE closes the logon requests queue. An INQUIRE issued by another 
application program would indicate this, and any attempt to direct a logon request 
to STOCK would fail. 
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Return of Status Information After SETLOGON processing is finished the following RPL fields are set: 

If OPTCD=QUIESCE, the number of logon requests queued for the ACB is set in 
the RECLEN field. This quantity can be examined with the SHOWCB macro 
instruction (a four-byte work area is required) or the TESTCB macro 
instruction. 

The value 21 (decimal) is set in the REQ field, indicating a SETLOGON request. 



The RTNCD and FDBK2 fields are set as indicated in Appendix C. 
Registers and 15 are also set as indicated in Appendix C. 
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SHOW CB— Extract the Contents of Control Block Fields 



SHOWCB extracts the contents of one or more ACB, EXLST, RPL, or NIB fields 
and places them into an area designated by the application program. The SHOWCB 
user specifies the address of a control block and the names of the fields whose 
contents are to be extracted. The field names are the same as the keywords of the 
ACB, EXLST, RPL, and NIB macro instructions. Any keyword of these macro 
instructions can be used as a field name in the SHOWCB macro instruction. See 
Appendix E for a list and explanation of the valid formats in which the SHOWCB 
operands can be specified. 

Control block fields that can be operated on by SHOWCB are not limited, however, 
to fields that can be set by the application programmer in the ACB, EXLST, RPL, 
and NIB macros. Several additional fields whose contents are set only by VTAM 
can also be displayed with SHOWCB. All of the fields applicable for SHOWCB are 
shown in Figure 13 at the end of the SHOWCB macro instruction description. 

The user of SHOWCB must use the AREA and LENGTH operands to indicate the 
location and length of the area where the fields will be placed. The content of each 
field is placed there contiguously, in the order indicated by the FIELDS operand. If 
the area is too short to hold all of the fields, SHOWCB returns error codes in 
register and 15. Figure 13 shows the required lengths for all the control block 
fields that can be displayed with SHOWCB. 

List, generate, and execute forms of the SHOWCB macro instruction are available; 
they are designated by the MF operand. 



Name 


Operation 


Operands 


[symbol] 


SHOWCB 


AM=VTAM 






( , ACB=acb address J 








) , EXLST=exit list address ( 








J , RPL=rpl address ( 








_ ' , NIB=nib address )_ 








, FIELDS=field name | (field name,...) 






, AREA=data area address 






, LENGTH=data area length 






[, MF=list, generate, or execute form parameters] 



AM=VTAM 

Identifies this macro instruction as a macro instruction capable of manipulating a 
VTAM control block. This operand is required. 

ACB=acb address 
EXLST=exit list address 
RPL=rpl address 
NIB=nib address 

Indicates the type and location of the control block whose fields are to be 
extracted. One of these operands must be specified unless a control block length 
(and only the length) is being extracted. That is, if FIELDS=ACBLEN, FIELDS= 
EXLLEN, FIELDS=RPLLEN, or FIELDS=NIBLEN is specified, no specific control 
block need be specified. 
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Examples 



FIELDS=field name | (field name,...) 

Indicates the control block field or fields whose contents are to be extracted. 

For field name, code one of the field names that appear in the first column of the 
table that appears at the end of this macro instruction description (Figure 13). Most 
of these field names correspond to keywords of the ACB, EXLST, RPL, and NIB 
macro instructions. Only those fields associated with one control block can be 
specified (those for the control block whose address is supplied in the first 
operand). 

AREA=work area address 

Indicates the location of the storage area in the application program where the 
contents of the control block field or fields are to be placed. This work area must 
begin on a fullword boundary. 

LENGTH=work area length 

Indicates the length (in bytes) of the storage area designated by the AREA operand. 

If this length is insufficient, SHOWCB returns a value of 4 in register 15 
(unsuccessful completion) and a value of 9 in register (insufficient length). The 
required length for each field is shown in the second column of the table that 
appears at the end of this macro instruction description. 

MF=list, generate, or execute form parameters 

Indicates that a list, generate, or execute form of SHOWCB is to be used. Omitting 
this operand causes the standard form of SHOWCB to be used. See Appendix F for 
a description of the nonstandard forms of SHOWCB. 

SHOW1 SHOWCB NIB=NIB1,FIELDS=NAME,AREA-NAME1, 

LENGTH=4,AM=VTAM 

SHOW1 extracts the contents of NIBl's NAME field and places it in NAME1. 

SHOW2 SHOWCB RPL=RPL1,FIELDS=(FDBK,ARG,AREA,RECLEN), 

AREA=(3),LENGTH=16,AM=VTAM 

SHOW2 extracts the contents of RPLl's FDBK, ARG, AREA, and RECLEN 

fields and places them (in that order) in a storage area. The address of this storage 
area must be in register 3 when SHOW2 is executed. Note that LENGTH indicates a 
storage area length great enough to accommodate all four fields. 



Return of Status Information 



After SHOWCB processing is completed, VTAM sets register 15 to indicate 
successful or unsuccessful completion. If the operation is completed successfully, 
register 15 is set to and register contains the total number of bytes that 
SHOWCB extracted and placed in the work area. If the operation completes 
unsuccessfully, register 15 is set to either 4 or 8. If it is set to 4, register is also set 
indicating the specific nature of the error (see Appendix D). 



Control Block Fields 
Applicable for SHOWCB 



The field names shown in the first column of Figure 13 are the values that can be 
supplied for the FIELDS operand of the SHOWCB macro instruction. The lengths 
shown in the second column are the number of bytes of storage that must be 
reserved for each field; the sum of all the fields to be displayed by SHOWCB should 
be the value for the LENGTH operand. 
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Field Name 

APPLID 

PASSWD 

EXLST 

ACBLEN 

ERROR 



Field Name 

LERAD 

SYNAD 

DFASY 

RESP 

SCIP 

TPEND 

RELREQ 

LOGON 

LOSTERM 

ATTN 

EXLLEN 



Field Name 

ACB 

NIB 

ARG 

AREA 

AREALEN 

RECLEN 

AAREA 

AAREALN 

ARECLEN 

ECB 

EXIT 

RTNCD 

FDBK2 

FDBK 

USER 

REQ 

RPLLEN 

SENSE 

SEQNO 

SSENSMO 

USENSEO 
SSENSMI 

USENSEI 
IBSQVAL 
OBSQVAL 
SI G DATA 



Field Name 

NAME 

USERFLD 

CID 

NIBLEN 

DEVCHAR 

EXLST 

RESPLIM 



> Address of exit-routine 



ACB Fields 

Length (bytes) Description 

4 Address of application program's symbolic name 

4 Address of password 

4 Address of exit list 

4 Length of ACB, in bytes 

4 OPEN and CLOSE completion code 

EXLST Fields 

Length (bytes) Description 
4 *N 
4 
4 
4 
4 
4 
4 
4 
4 
4 

4 Length of exit list, in bytes 

RPL Fields 

Length (bytes) Description 

4 Address of ACB 

4 Address of NIB 

4 CID of terminal 

4 Address of I/O work area 

4 Length of AREA work area, in bytes 

4 Length of data in AREA work area, in bytes 

4 Address of alternate I/O area 

4 Length of AAREA, in bytes 

4 Length of data placed in alternate I/O area 

4 ECB or address of an ECB 

4 Address of RPL exit-routine 

4 Recovery return code (1 byte, right-adjusted) 

4 Specific error return code (1 byte, right-adjusted) 

4 Status information about successful input 

operations (1 byte, right-adjusted) 

4 The data originally placed in a NIB's USERFLD 

field 

4 Request-type code (1 byte, right-adjusted) 

4 Length of RPL, in bytes 

4 Device sense and status (2 bytes, right-adjusted) 

4 Sequence number 

4 Outbound system sense modifier (1 byte, right- 
adjusted) 

4 Outbound user sense (2 bytes, right-adjusted) 

4 Inbound system sense modifier (1 byte, right- 
adjusted) 

4 Inbound user sense (2 bytes, right-adjusted) 

4 Inbound sequence number for STSN indicator 

4 Outbound sequence number for STSN indicator 

4 Information included with signal indicator 

NIB Fields 

Length (bytes) Description 

8 Symbolic name of terminal 

4 Arbitrary data associated with NAME 

4 Communication ID 

4 Length of NIB, in bytes 

8 Device characteristics (see Appendix H) 

4 Address of N IB-oriented exit list 

4 Maximum number of concurrent SEND 
(POST=RESP) macros 



Figure 13. Control Block Fields That Can Be Extracted with SHOWCB 
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SIM LOGON— Generate a Simulated Logon Request 



A logon request can be initiated (1) by VTAM, in accordance with VTAM 
definition specifications, (2) by some other application program, which directs the 
logon request toward your application program, (3) by the network operator, (4) 
by the network solicitor or by the terminal itself, or (5) by your own application 
program. The latter is called a simulated logon request, and the program uses the 
SIMLOGON macro instruction to generate it. 

By issuing SIMLOGON, the application program can use its LOGON exit-routine to 
service self-initiated logon requests. When used this way, SIMLOGON is equivalent 
to an OPNDST connection request with an ACQUIRE processing option, except 
that the LOGON exit-routine handles the connection request. As is true with 
OPNDST (OPTCD= ACQUIRE), the terminal may already be connected to another 
application program when you issue SIMLOGON. 

Note: Do not issue SIMLOGON if the ACB was opened with MACRF=NLOGON, 
or if no LOGON exit-routine is available when SIMLOGON is executed. 

SIMLOGON can be issued without a LOGON exit-routine; in this situation, 
SIMLOGON causes any OPNDST (OPTCD=ACCEPT) macro instruction to be 
satisfied. 

The LOGON exit-routine is scheduled as soon as the terminal is available for use by 
the application program. If the terminal is a dial-in terminal, the exit is scheduled 
when the terminal operator dials in. For dial-out terminals, the LOGON 
exit-routine is scheduled as soon as the terminal becomes available, but the terminal 
is not actually dialed until the first I/O request is directed at the terminal. (A 
terminal is available if it has been included as a part of VTAM definition, and is not 
connected to another application program.) 

The SIMLOGON macro is the only way that an application program can acquire a 
dial-in terminal because SIMLOGON is the only form of acquisition that can be 
queued (OPTCD=Q). 

If a terminal has been defined as a dial-in terminal by the installation (CALL=IN 
specified for the LINE or GROUP definition statement), a SIMLOGON request 
with OPTCD=Q is completed when the terminal operator dials in. For a dial-in BSC 
terminal, the first I/O request following connection must be a SOLICIT or READ 
(OPTCD=SPEC) request. 

If you acquire a dial-in terminal without the ID verification feature, you can 
establish the identity of the terminal only by issuing I/O requests and obtaining 
information from the terminal operator. If the terminal has the ID verification 
feature, INQUIRE (OPTCD=BSCID) can be used to obtain the terminal's 
identification sequence. 

The SIMLOGON macro instruction can optionally be used to send a logon message 
along with the logon request. See the AREA and RECLEN operands below for 
details. 

The use of SIMLOGON must be authorized for the application program by the 
installation. 
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Name 


Operation 


Operands 


[symbol] 


SIMLOGON 


RPL=rpl address 

[ , rpl field name=new value] ... 



RPL=rpl address 

Indicates the location of the RPL to be used during SIMLOGON processing. The 
NIB field of this RPL should contain the address of a NIB or list of NIBs whose 
associated terminals are to be considered as the sources of the logon requests. The 
ACB field of the RPL must contain the address of the ACB to which the simulated 
logon request is to be directed. 

rpl field name=new value 

Indicates an RPL field to be modified and the new value that is to be contained 
within it. If you wish to avoid the possibility of program reassembly following 
future releases of VTAM, set the RPL field with MODCB macro instructions rather 
than with the SIMLOGON macro instruction. 

Format: For rpl name code the keyword of the RPL macro instruction operand 
that corresponds to the RPL field to be modified. The new value can be any value 
that is valid for that operand in the RPL macro instruction, or it can indicate a 
register. 

Although any RPL operand can be specified, the following operands apply to a 
SIMLOGON macro instruction: 

ACB=acb address 

Indicates the ACB that identifies the application program to which the simulated 
logon request is to be directed. 

NIB=nib address 

Indicates the NIB whose NAME field identifies the terminal for which the 
simulated logon request is to be generated. If the NIB field contains the address of a 
list of NIBs, logon requests will be generated on behalf of all the terminals of that 
list. 

AREA=iogon message address 

VTAM passes this data to the application program as a logon message. The other 
application program issues INQUIRE (OPTCD=LOGONMSG) to get this data. 

RECLEN=logon message length 

Indicates how many bytes of data are to be passed as the logon message. If no logon 
message is to be sent, RECLEN should be set to 0. 

ECB | EXIT=ecb or rpl exit-routine address 

Indicates the action to be taken by VTAM when an asynchronous (OPTCD=ASY) 
SIMLOGON macro instruction is completed. The macro instruction is completed 
when the simulated logon request has been generated. If EXIT is specified, the RPL 
exit-routine is scheduled. Otherwise the ECB is posted, and CHECK or WAIT must 
be used to determine when the posting occurs. See the RPL macro instruction for 
more information. 
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OPTCD=SYN|ASY 

When the SYN option code is set, control is returned to the application program 
when the macro instruction has been completed. When ASY is set, control is 
returned as soon as VTAM has accepted the request. Once the macro instruction 
has been completed, the ECB is posted or the RPL exit-routine is scheduled, as 
indicated by the setting of the ECB-EXIT field. 

OPTCD=CONANY | CONALL 

When CONANY is set, a logon request is generated for the first available terminal in 
the NIB list. When CONALL is set, a logon request is generated for each available 
terminal in the NIB list. If there is only one NIB, the setting of this option code 
does not matter. 

OPTCD=Q|NQ 

When Q is set, LOGON exit-routine is scheduled as the terminal or terminals 
become available. When NQ is set, the SIMLOGON operation fails if the terminal or 
terminals are not immediately available. 

OPTCD=RELRQ INRELRQ 

This option code is meaningful only if the Q option code is set. When RELRQ is 
set, VTAM invokes the owning application program's RELREQ exit-routine. If 
NRELRQ is set, the owning application program is not notified of your request for 
its terminal. (The owning application program is the application program to which 
the terminal is currently connected.) 



Example 



SIM1 SIMLOGON 



RPL=RPL1 ,ACB=ACB 1 ,NIB=NIBLIST 1 , 

AREA=LGNMSG,RECLEN=60,EXIT=CHECKPGM 

OPTCD=(ASY,CONALL,NRELRQ,Q) 



LGNMSG 


DC 


ACB1 


ACB 


NIBLIST1 


NIB 




NIB 




NIB 



CL60'LOGON FROM NIBLIST1 STATION' 

MACRF=LOGON 

NAME=STATIONA,MODE=BASIC,LISTEND=NO 

NAME=STATIONB,MODE=BASIC,LISTEND=NO 

NAME=STATIONC,MODE=BASIC,LISTEND=YES 



SIM1 generates simulated logon requests for ACB1 from all of the terminals 
represented in NIBLIST1. Each request will be accompanied by a 60-byte logon 
message taken from LGNMSG. The CONALL option code indicates that requests 
are to be generated for all the terminals represented in the list. NRELRQ indicates 
that if any of the terminals of NIBLIST1 are connected to an ACB other than 
ACB1, that ACB's RELREQ exit-routine is not to be scheduled. After SIM1 is 
completed, control is transferred to CHECKPGM. 

Return of Status Information When the SIMLOGON operation is completed, the following RPL fields are set: 

The value 22 (decimal) is placed in the REQ field, indicating a SIMLOGON 
request. 

The RTNCD and FDBK2 fields are set as indicated in Appendix C. 

Registers and 15 are also set as indicated in Appendix C. 
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SOLICIT— Obtain Data from a Terminal (Basic-mode only) 



The SOLICIT macro instruction obtains data from one or more connected BSC or 
start-stop terminals. A subsequent READ macro instruction is required to move the 
data from VTAM buffers to the input area provided by the application program. 

SOLICIT performs the preparation or polling required to obtain the data and 
supplies appropriate line-control responses as blocks of data are obtained. 
(SOLICIT does not unlock the keyboard of a 3270 display station; this can be done 
with a WRITE macro instruction if an unlock-keyboard control character is 
included in the data stream.) 

The SOLICIT macro instruction is completed as soon as VTAM has accepted the 
request. The actual solicitation of data continues as indicated by the BLOCK-MSG- 
TRANS-CONT processing option used when the terminal being solicited was 
connected. The effect of these options is summarized below; see the NIB macro 
instruction description (including Figure 5) for more information. 

PROC=BLOCK 

One block of data ending in an EOB line control character (for start-stop devices) 
or an ETB line-control character (for binary synchronous devices) is obtained. 

PROC=MSG 

Blocks of data are continuously obtained until a block containing an EOT character 
(for start-stop devices) or an ETX character (for binary synchronous devices) is 
received. In effect, this means that data is solicited from the terminal until an entire 
message has been received. 

PROC=TRANS 

Blocks of data are continuously obtained until a block containing an EOT character 
is recognized. In effect, this means that data is solicited from the terminal until an 
entire transmission has been received. 

PROC=CONT 

Blocks of data are continuously solicited from the terminal. This solicitation 
continues indefinitely, unless the request is canceled with the RESET macro 
instruction, or the terminal becomes disconnected from the program. 

SOLICIT does not obtain data from a terminal if the application program has not 
read all previously solicited data, or if the CS option code was in effect for the last 
I/O request directed at the terminal. 

Any I/O errors that occur during solicit operations for a given terminal become 
known to the program only when it next issues a READ or WRITE macro for that 
terminal. 



Name 


Operation 


Operands 


[symbol] 


SOLICIT 


RPL=rpI address 

[ , rpl field name=new value] ... 
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RPL=rpl address 

Indicates the location of the RPL that governs the solicit operation. 

rpl keyword=new value 

Indicates an RPL field to be modified and the new value that is to be contained or 
represented within it. If you wish to avoid the possibility of program reassembly 
following future releases of VTAM, set the RPL field with MODCB macro 
instructions rather than with the SOLICIT macro instruction. 

Format: For rpl field name, code the keyword of the RPL macro instruction 
operand that corresponds to the RPL field being modified. ARG can also be coded. 
The new value can be any value that is valid for that operand in the RPL macro 
instruction, or it can indicate a register. The value supplied for the ARG keyword 
must indicate a register. 

Although any RPL operand can be specified, the following operands apply to a 
SOLICIT macro instruction: 

ACB=acb address 

Indicates the ACB that identifies the application program. 

ARG=(register) 

If a specific terminal is to be solicited, the ARG field of the RPL must contain the 
CID of that terminal. ARG=(register) is indicated here because register notation 
must be used to place the CID in the RPL with this SOLICIT macro instruction. 
ARG does not apply to SOLICIT when the ANY option code is set. 

ECB | EXIT=ecb or rpl exit-routine address 

Indicates the action to be taken by VTAM when an asynchronous (OPTCD=ASY) 
SOLICIT macro instruction is completed. The macro instruction is completed 
immediately, subject to delays due to possible storage shortages. If EXIT is speci- 
fied, the RPL exit-routine is scheduled. Otherwise the ECB is posted, and CHECK 
or WAIT must be used to determine when posting occurs. See the RPL macro 
instruction for more information. 

OPTCD=SYN|ASY 

When the SYN option code is set, control is returned to the application program 
when the SOLICIT macro instruction has been completed. When ASY is set, 
control is returned when the macro instruction has been accepted. Although a 
SOLICIT macro instruction is usually completed immediately after the macro 
instruction has been accepted, a storage shortage could cause a delay. Upon return 
of control from an asynchronous SOLICIT, the ECB is posted or or the RPL 
exit-routine is scheduled, as indicated by the setting of the ECB-EXIT field. 

OPTCD=CA | CS 

When the CA option code is set, the data obtained from the solicit operation is 
available for a subsequent READ (OPTCD=ANY). When CS is set instead, and the 
SPEC option code is also set, only a subsequent READ (OPTCD=SPEC) can be used 
to retrieve the data obtained by the solicit operation. If the ANY option code is set, 
the CA-CS option code is treated as though CA had been specified, regardless of the 
actual setting. 

OPTCD=SPEC|ANY 

When the SPEC option code is set, data is solicited from only one terminal; namely 
the terminal whose CID has been placed in the ARG field of the SOLICIT macro's 
RPL. When ANY is set, data is solicited from all terminals that are connected to the 
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program and are not already being solicited. If only one terminal is available for 
solicitation, avoid using SOLICIT (OPTCD=ANY). It will work, but it takes more 
time than SOLICIT (OPTCD=SPEC). 



Examples 



SLCT1 



SOLICIT RPL=RPLl,OPTCD=ANY 



RPL1 



RPL 



ACB=ACB1 



SLCT1 causes data to be solicited from any terminal that has been connected 
through ACB1 and is not currently engaged in communication with the application 
program. 



SLCT2 



SOLICIT RPL=RPL2,OPTCD=SPEC,ARG=(6) 



RPL 



RPL 



ACB=ACB1 



SLCT2, which represents a more likely use of SOLICIT, causes data to be solicited 
from the terminal whose CID is in RPL2's ARG field. 



Return of Status Information 



Control is returned to the program when VTAM has accepted the request, not when 
the actual I/O activity is eventually completed. After control has been returned, 
these RPL fields are set: 

If OPTCD=SPEC is specified for in SOLICIT, the USER field is set. When a NIB 
is created, the application program has the option of specifying any value in the 
USERFLD field of that NIB. When the SOLICIT macro instruction is 
subsequently issued for the terminal connected with that NIB, VTAM obtains 
the value that was set in the USERFLD field and places it in the RPL's USER 
field. 

The value 30 (decimal) is set in the REQ field, indicating a SOLICIT request. 

The RTNCD and FDBK2 fields are set as indicated in Appendix C. 

Registers and 15 are also set as indicated in Appendix C. 
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TESTCB-Test the Contents of a Control Block Field 



TESTCB compares the contents of a specified ACB, RPL, EXLST, or NIB field 
with a value supplied with the macro instruction, and sets the PSW condition code 
accordingly. 

The user of the TESTCB macro instruction indicates a particular control block, 
identifies a single field within that control block, and supplies the value against 
which the contents of that field are to be tested. Figure 14 lists the control block 
fields that can be tested. 

The operands for testing control block fields are used in much the same way as 
operands for modifying or setting control block fields in macros like MODCB or 
GENCB. For example, RECLEN=200 in a MODCB macro places the value 200 in 
the RECLEN field of an RPL; if RECLEN=200 is specified in a TESTCB macro 
instruction, the contents of the RECLEN field are compared with the value 200. 
See Appendix E for a list and explanation of the various formats in which the 
TESTCB operands can be coded. 

The test performed by TESTCB is a logical comparison between the field's actual 
content and the specified value. The condition code indicates a high, equal, or low 
result (with the actual content considered as the "A" comparand of the "A:B" 
comparison). The TESTCB macro instruction can be followed by any branching 
instructions that are valid following A compare instruction. 

TESTCB can be used to test any control block field whose content can be set by 
the application program, as well as some of the control block fields whose contents 
are set by VTAM. The explanation below of the field name operand indicates the 
fields that can be tested. 

With the ERET operand of the TESTCB macro instruction, the application program 
can supply the address of an error-handling routine. This routine is invoked if some 
error condition prevents the test from being performed correctly. 

List, generate, and execute forms of TESTCB are available; they are designated by 
the MF operand. 



Name 


Operation 


Operands 


[symbol] 


TESTCB 


AM=VTAM 








( , ACB=acb address \ ~" 










) , EXLST=exit list address f 










J , RPL=rpl address C 










[ , NIB=nib address ) 








, field name=test value 






[ , ERET=error exit routine address] 






[, MF=list, generate, or execute form parameters] 



AM=VTAM 

Identifies this macro instruction as a VTAM macro instruction. This operand is 
required. 
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ACB=acb address 
EXLST=exit list address 
RPL=rpl address 
NIB=nib address 

Indicates the type and location of the control block whose field is to be tested. 

This operand is normally required, but can be omitted if a control block length is 
being tested. (Control block lengths are tested by specifying ACBLEN, EXLLEN, 
RPLLEN, or NIBLEN for the TESTCB macro instruction). Since every control 
block of a given type is the same length for a given operating system, it is not 
necessary for you to indicate which ACB, EXLST, RPL, or NIB you want to know 
the length of. 

field name=test value 

Indicates a control block field and a value that its contents are to be tested against. 
For field name, code one of the field names that appear in the table at the end of 
this macro instruction description (Figure 14). 

The rules for coding test value are defined and summarized in Appendix E. 

Examples: TESTCB ACB=ACB1,PASSWD=(6),AM=VTAM 

TESTCB EXLST=EXLST 1 ,S YNAD=S YNADPGM, 

AM=VTAM 
TESTCB RPL=RPL 1 ,AREALEN=64,AM=VTAM 

TESTCB NIB=NIB1,LISTEND=YES,AM=VTAM 

Examples: TESTCB ACB=ACBl,OFLAGS=OPEN,AM=VTAM 

TESTCB RPL=RPL1,RPLLEN=38,AM=VTAM 

RPL option codes or NIB processing options (including combinations of them) can 
also be tested. The test results in an equal condition code if all of the specified 
options are present. The first example below shows how to test for the presence of 
the SPEC, CS, and BLK option codes of an RPL. The second example illustrates 
how to code a similar test for the MSG, CONFTXT, and MONITOR processing 
options of a NIB. 

Examples: TESTCB RPL=RPLl,OPTCD=(SPEC,CS,BLK),AM=VTAM 

TESTCB NIB=NIB 1 ,PROC=(MSG,CONFTXT,MONITOR), 

AM=VTAM 

ERET=error routine address 

Indicates the location of a routine to be entered if TESTCB processing encounters a 
situation that prevents it from performing the test. 

When the ERET routine receives control, register 15 indicates the nature of the 
error. These return codes are described in Appendix D (and are summarized below). 



Note: If this operand is omitted, the program instructions that follow the TESTCB 
macro instruction should check register 15 to determine whether an error occurred 
(indicating that the PSW condition code is meaningless) or not. To make this check 
without disturbing the condition code, a branching table based on register 15 can 
be used. 

MF=list, generate, or execute form parameters 

Indicates that a list, generate, or execute form of TESTCB is to be used. Omitting 
this operand causes the standard form of TESTCB to be used. See Appendix F for a 
description of the nonstandard forms of TESTCB. 
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Return of Status Information After TESTCB processing is finished and control is either passed to the ERET error 

routine or returned to the next sequential instruction, register 1 5 indicates whether 
or not the test was completed successfully. If the test completed successfully, 
register 15 is set to 0; if it completed unsuccessfully, register 15 is set to either 4 or 
8. If it is set to 4, register is also set indicating the specific nature of the error (see 
Appendix D). 

Control Block Fields The field names shown in the first column of Figure 14 are the values that can be 

Applicable for TESTCB coded for the field name operand of the TESTCB macro instruction. The second 

column indicates the number of bytes that each field occupies. No lengths are 
shown for fields that can only be tested using fixed values (for example, 
MACRF=LOGON or CONTROL=QEC). 
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Field Name 

APPLID 

PASSWD 

EXLST 

ACBLEN 

ERROR 

OFLAGS 

MACRF 



Field Name 

LERAD 

SYNAD 

DFASY 

RESP 

SCIP 

TPEND 

RELREQ 

LOGON 

LOSTERM 

ATTN 

IEXLLEN 



Field Name 

ACB 

NIB 

ARG 

AREA 

AREALEN 

RECLEN 

AAREA 

AAREALN 

ARECLEN 

ECB 

EXIT 

RTNCD 

FDBK2 

FDBK 

DATAFLG 

10 

USER 

REQ 

RPLLEN 

SENSE 

BRANCH 

OPTCD 

SEQNO 

SSENSEO 

SSENSMO 

USENSEO 

SSENSEI 

SSENSMI 

USENSEI 

IBSQAC 

OBSQAC 

IBSQVAL 

OBSQVAL 

POST 

RESPOND 

CONTROL 



ACB Fields 

Length (bytes) Description 

4 Address of application program's symbolic name 

4 Address of password 

4 Address of exit list 

2 Length of ACB, in bytes 

1 OPEN and CLOSE completion codes 

ACB open-closed indicator (OFLAGS=OPEN) 
Logon request status (MACRF=LOGON| NLOGON) 

EXLST Fields 

Length (bytes) Description 
4 
4 
4 
4 
4 
4 
4 
4 
4 
4 
2 



> Address of exit-routine 



Length (bytes) 
4 
4 
4 
4 
4 
4 
4 
4 
4 
4 
4 
1 
1 
1 



Length of exit list, in bytes 

RPL Fields 

Description 

Address of ACB 

Address of NIB 

CID of terminal 

Address of I/O work area 

Length of AREA work area, in bytes 

Length of data in AREA work area, in bytes 

Address of alternate I/O work area 

Length of AAREA work area, in bytes 

Length of data in AAREA work area, in bytes 

ECB or address of ECB 

Address of RPL exit-routine 

General return code 

Specific error return code 

Additional status information 

Alias for FDBK 

RPL inactive flag (IO=COMPLETE) 

USE RFLD data 

Request type code 

Length of RPL, in bytes 

Device sense and status information (BSC) 

SRB indicator (BRANCH=YES| NO, 0S/VS2 only) 

RPL option code 

Sequence number 

Outbound system sense indicator 

Outbound system sense modifier value 

Outbound user sense value 

Inbound system sense indicator 

Inbound system sense modifier value 

Inbound user sense value 

Inbound action code for STSN indicator 

Outbound action code for STSN indicator 

Inbound sequence number for STSN indicator 

Outbound sequence number for STSN indicator 

Scheduled or responded output 

(POST=SCHED|RESP) 

Response indicator (RESPOND=EX|NEX, 

FMEJNFME, RRN|NRRN) 

Control indicator (CONTROL=DATA| indicator) 



Figure 14. Control Block Fields That Can Be Tested with TESTCB (Part 1 of 2) 
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RPL Fields (Cont.) 

Field Name Length (bytes) Description 

CHAIN - Chain indicator (CHAIN=FIRST|MIDDLE|LAST| 

ONLY) 
CHNGDIR - Change-direction indicator (CHNGDIR=CMD I 

NCMD, REQ|NREQ) 
BRACKET - Bracket indicator (BRACKET=BB | NBB, EB | NEB) 

RTYPE - Receive-type indicator (DFSYN, DFASY, RESP) 

STYPE - Send-type indicator (STYPE=REQ | RESP) 

SIGDATA 4 Information included with a signal indicator 

NIB Fields 

Field Name Length (bytes) Description 

NAME 8 Symbolic name of terminal 

USERFLD 4 Arbitrary data associated with NAME 

CID 4 Communication ID 

NIBLEN 2 Length of NIB, in bytes 

DEVCHAR 8 Device characteristics (see Appendix H) 

EXLST 4 Address of N IB-oriented exit list 

RESPLIM 4 Maximum number of concurrent SEND 

(POST=RESP) macros 

MODE - Mode indicator (MODE=BASIC I RECORD) 

LISTEND - NIB list termination flag (LISTEND=YES| NO) 

SDT - Start-data-traffic flag (SDT=APPL | SYSTEM) 

PROC - Processing option codes 

CON - Terminal-connected flag (CON=YES) 

I 

Figure 14. Control Block Fields That Can Be Tested with TESTCB (Part 2 of 2) 
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WRITE— Write a Block of Data to a Terminal (Basic-mode only) 



The WRITE macro instruction obtains a block of data from a designated area in 
application program storage and sends it to a specific terminal. 

There are several variations for WRITE: 

• The write operation can be followed automatically by a read operation, as 
though a READ macro instruction had been coded after the WRITE macro. This 
composite operation is called a conversational write operation. 

• The write operation can be preceded by the erasure of the 2265 screen of a 2770 
Data Communication Terminal or a 3270 display device. 

• The unprotected portion of a display screen in a 3270 display device can be 
erased (with no associated write operation performed). 

Note: Following connection, you cannot write to a 3735 Programmable Buffered 
Terminal until you first issue a SOLICIT or READ (OPTCD=SPEC) macro 
instruction for the terminal. 

Should a write operation be pending (or in progress) when another WRITE macro 
instruction is issued, the first operation is completed before the second operation is 
performed. This means that several WRITE macro instructions for a particular 
terminal can be issued serially. If data is being solicited from a terminal when the 
write macro instruction is issued, the write operation is suspended until the 
solicitation is completed. Since this may take some time, you may wish to cancel 
the SOLICIT request with a RESET macro instruction. Furthermore, if the 
terminal is a BSC device and data is being received which is not at an ETX 
(message) boundary, the WRITE macro instruction fails and a return code is placed 
in the RPL's FDBK2 field. See the SOLICIT macro instruction for a description of 
what constitutes and controls the completion of a solicit operation. 

The TRUNC-KEEP processing option in the NIB determines how excess input data 
is to be handled for a conversational WRITE macro instruction. When the TRUNC 
processing option is in effect and the CONV option code is set, and there is too 
much incoming data to fit in the area indicated by AAREA, the data is truncated, 
the remainder is lost, and the WRITE macro instruction terminates with an I/O 
error. With KEEP however, the remainder is saved and passed to the program when 
the next READ macro instruction is issued for that terminal. 



Name 


Operation 


Operands 


[symbol] 


WRITE 


RPL=rpI address 

[, rpl field name=value] ... 



RPL=rpl address 

Indicates the location of the RPL that governs the write operation. 

rpl field name=new value 

Indicates an RPL field to be modified and the new value that is to be contained or 
represented within it. If you wish to avoid the possibility of program reassembly 
following future releases of VTAM, set the RPL field with MODCB macro 
instructions rather than with the WRITE macro instruction. 
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Format: For rpl field name, code the keyword of the RPL macro instruction 
operand that corresponds to the RPL field being modified. ARG can also be coded. 
The new value can be any value that is valid for that operand in the RPL macro 
instruction, or it can indicate a register. The value supplied for the ARG keyword 
must indicate a register. 

Although any basic-mode RPL operand can be specified, the following operands 
apply to the WRITE macro instruction: 

ACB=acb address 

Indicates the ACB that was used when the terminal was connected. 

ARG=(register) 

The ARG field of the RPL must contain the CID of the terminal to which the data 
is to be written (see the OPNDST macro instruction for an explanation of the CID). 
ARG=(register) is indicated here because register notation must be used when the 
CID is placed in the ARG field with this WRITE macro instruction. 

AREA=output data address 

The data contained at the location indicated by AREA is sent to the terminal. Since 
the application cannot determine the exact moment that VTAM moves the data 
from this area, the area should not be reused until the WRITE macro instruction is 
completed. 

RECLEN=output data length 

The number of bytes of data indicated in the RECLEN field is sent to the terminal. 
If this field is set to and OPTCD=LBT (explained below), an EOT is sent to the 
terminal. If OPTCD=BLK or OPTCD=LBM, the line control characters shown in 
Appendix B are sent without data. 

AAREA=input data area address 

When the CONV option code is set, the data obtained from the terminal following 
the output operation is placed in the storage area indicated by the A ARE A field. 
VTAM also places the length of this data in the ARECLEN field. The AAREA field 
is not used if NCONV is set. 

AAREALN=input data area length 

AAREALN indicates the capacity of the data area pointed to by AAREA. If the 
amount of incoming data exceeds the capacity of this data area, the action 
indicated by the TRUNC-KEEP option code is taken. 

ECB | EXIT=ecb or rpl exit-routine address 

Indicates the action to be taken by VTAM when an asynchronous (OPTCD=ASY) 
WRITE macro instruction is completed. The macro instruction is completed after 
the data has been received and acknowledged by the terminal (or, for a 
conversational WRITE, as soon as the input data has been moved into the 
application program's storage area). If EXIT is specified, the RPL exit-routine is 
scheduled. Otherwise the ECB is posted, and CHECK or WAIT must be used to 
determine when the posting occurs. See the RPL macro instruction for more 
information. 

OPTCD=SYN|ASY 

When the SYN option code is set, control is returned to the application program 
when the WRITE macro instruction has been completed. When ASY is set, control 
is returned as soon as VTAM has accepted the request. Once the WRITE macro 
instruction has been completed, the ECB is posted or the RPL exit-routine is 
scheduled, as indicated by the setting of the ECB-EXIT field. 



160 



WRITE 



OPTCD=BLK|LBM|LBT 

These option codes determine whether the line-control characters selected by the 
system for transmission with the data should mark the data as the end of a block, 
the end of a message, or the end of a transmission. 

When the BLK option code is set, the line-control characters indicated in Appendix 
B under "BLK" are sent with the block of data. BLK is invalid for a 3270 
terminal. 

When the LBM option code is set, the line-control characters indicated in Appendix 
B under "LBM" are sent with the block of data. 

When the LBT option code is set, the line-control characters indicated in Appendix 
B under "LBT" are sent with the block of data. After the block of data is 
acknowledged by the terminal an EOT character is sent. The write operation is 
considered complete when the EOT character has been sent. 

OPTCD=CONV | NCONV 

When NCONV is set, no read operation follows the write operation. When the 
CONV option code is in effect, an input operation is performed after the block of 
data has been written to the terminal. The data received in response to the write 
operation is placed in the area indicated by the RPL's AAREA field, and the length 
of that data is set in the ARECLEN field. 

Should the terminal merely respond with an acknowledgement and not data, the 
following action is taken: An EOT is sent to the terminal and the terminal is polled 
(or for a point-to-point line, placed in the receive state). The input data eventually 
received from this polling is then placed in the AAREA and ARECLEN fields. The 
operation is not completed until the data is received. 

When a WRITE with OPTCD=CONV is issued, a second WRITE may not be issued 
to the same terminal until the first output operation is completed, unless the first 
operation is canceled with the RESET macro instruction. 

OPTCD=ERASE |EAU INERASE 

The ERASE and EAU option codes indicates that one of two special variations of 
WRITE are to be used; NERASE indicates that an ordinary output operation is 
requested. 

When ERASE is used, the entire display screen of (1) a 2265 display station 
attached to a 2770 Data Communication System or (2) a 3270 display station, is 
erased before the block of data is written to the terminal. ERASE cannot be 
specified for conversational WRITE operations (OPTCD=CONV); use the 
ERASELBM or ERASELBT LDOs followed by a chained READ LDO if a 
combined erase-write-read operation is desired. 

EAU means that the unprotected portion of a 3270 display station screen is to be 
erased, and its keyboard unlocked. No data is sent to the terminal. EAU cannot be 
specified for a conversational WRITE operation; use the EAU LDO followed by a 
chained READ LDO if a combined erase-read operation is desired. 

OPTCD=CS|CA 

When CA is set, data obtained from the terminal can satisfy a READ (OPTCD= 
ANY) macro instruction. When CS is set, only READ (OPTCD=SPEC) macro 
instructions can obtain data from the terminal. See the RPL macro instruction for 
more information. 
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Examples 



WRITE1 WRITE RPL=RPL1,AREA=SOURCE,RECLEN=60, 

EXIT=WRTDONE,OPTCD=ASY 

WRITE 1 sends a 60-byte block of data from SOURCE to the terminal. This 
example assumes that the CID for the terminal is already in RPLl's ARG field. 
Control is returned to the instruction following WRITE 1 as soon as the data has 
been written to the terminal and an acknowledgment has been received. When the 
operation is completed, the program is interrupted and control passed to 
WRTDONE. 



WRITE2 



MODCB 
WRITE 



RPL2,ARG=(3) 
RPL=RPL2 



WRITE2 erases the unprotected part of a 3270 display screen. The MODCB macro 
instruction places the contents of register 3 (the terminal's CID) into RPL2's ARG 
field. 



WRITE3 



WRITER 



RPL=RPL3 



Return of Status Information 



RPL3 RPLARE AREA=OUTGOING,RECLEN=120, 

AAREA=INCOMING,AAREALN= 1 32, 
OPTCD=(CONV,LBT) 

WRITE3 requests a conversational WRITE operation. 120 bytes of data from 
OUTGOING are sent to the terminal whose CID is in register 3. Data is then read 
from the terminal and placed into INCOMING. If more than 132 bytes are received, 
the excess will be lost. Because the LBT option code is set, the operation is not 
completed until the terminal responds with data. 

After a WRITE macro instruction has been completed, these RPL fields are set: 

If the CONV option is set, the ARECLEN field indicates the number of bytes of 
data obtained during the input part of the conversational operation. 

When a NIB is used during connection, VTAM associates the contents of the 
USERFLD field with the terminal. When the WRITE macro instruction is 
subsequently issued for the terminal, the contents of the USERFLD field is 
placed in the USER field of the RPL by VTAM. 

The value 17 (decimal) is set in the REQ field indicating a WRITE request. 

If the CONV* option code is set, the FDBK field is set: it contains information 
concerning the input portion of the operation. See the FDBK field description in 
Appendix C. 

The SENSE, RTNCD, and FDBK2 fields are set as indicated in Appendix C. 

Registers and 15 are also set as indicated in Appendix C. 

a conversational WRITE macro instruction. When the TRUNC processing option is 

in effect and the CONV option code is set, and there is too much incoming data to 
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APPENDIX A. SUMMARY OF CONTROL BLOCK FIELD USAGE 



After you have become familiar with the workings of the VTAM macro instructions 
described in this book, this appendix can be used as a quick reference. It shows the 
following information about all of the executable macro instructions in this book: 

• The control block fields that are set by the application program when (or 
before) the macro instruction is issued. 

• The control block fields and registers that are set by VTAM during macro 
instruction processing. 

Note: All of the control block fields that apply to the macro instruction are shown, 
but remember that not all fields apply to every possible variation of a macro 
instruction. Refer to the macro instruction descriptions if you are in doubt. 

Throughout this appendix, a pointer (-*) indicates that a field contains the address 
of the given item, and an equal-sign indicates that a field contains the item itself. 
You will also note that a horizontal dashed line is used with each macro instruction; 
all information above this line concerns information your application program 
supplies to the macro instruction, and all information shown below this line 
concerns information that the macro instruction passes back to your application 
program. 

CHANGE -» RPL: ACB field -> ACB to which terminal is connected 
NIB field-* modified NIB: 

CID field = CID of terminal 

USERFLD field = new data to be returned during subsequent 
I/O requests 

MODE field = BASIC 

PROC field = new set of processing options 
( ECB field -» fullwork area ) 
\ EXIT field -► RPL exit-routine J 
OPTCD field = (SYNIASY, CA|CS) 

Registers and 15 = return codes 

RPL: RTNCD field = recovery action return code 

FDBK2 field = specific error return code 

REQ field = request code 



CHECK 



RPL being checked 



RPL set inactive 

Registers and 15 = return codes 



CLOSE 



ACB being closed 



Register 15 = return code 

ACB : OFLAGS field = opened or not-opened indicator 
ERROR field = specific error return code 
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CLSDST -> RPL: ACB field -► ACB 

(NIB field -> NIB: NAME field = symbolic name of terminal to be ) 
\ disconnected / 

( ARG field = CID of terminal to be disconnected ) 

AAREA field ->• symbolic name of receiving application program 
AREA field -> logon message 
RECLEN field = length of logon message 
[ ECB field -» full word work area) 
\ EXIT field -► RPL exit-routine J 
OPTCD field = (PASSIRELEASE, SYN|ASY) 

Registers and 15 = return codes 
RPL: RTNCD field = recovery action return code 
FDBK2 field = specific error return code 

DO ^ RPL: ACB fields ACB 

ARG field = CID of terminal 
( ECB field ->■ fullword work area ) 
t EXIT field -► RPL exit-routine / 
OPTCD field = (SYNIASY, CS|CA) 
AREA field ->LDO: 

If CMD field = COPYLBM or COPYLBT, 

ADDR -> copy control character and sending device's CID 

(ARG field contains receiving device's CID) 
LEN = 3 
If CMD field = READ or READBUF, 
ADDR ->■ input data area 
LEN = length of data area 
If CMD field = ERASELBM or ERASELBT, 
ADDR -* output data 
LEN = length of data 
If CMD field = WRITE, WRITELBM, WRITELBT, WRTHDR, 
WRTNRLG, or WRTPRLG, 
ADDR -»• output data 
LEN = length of output data 

Registers and 15 = return codes 
RPL: AAREA field -> last LDO used 

USER field -+ data from USERFLD field of NIB 

RECLEN field = length of data received 

FDBK field = status information (if CMD field = READ) 

RTNCD field = recovery action return code 

FDBK2 field = specific error return code 

REQ field = request code 

EXECRPL -> RPL: All fields appropriate for the request type (indicated in the REQ field) 
are valid. 

GENCB AM = VTAM 

BLK operand = control block type 

control block field name operand = value to be set in field 

COPIES operand = number of copies desired 

WAREA operand -> work area where blocks will be built 

LENGTH operand = length of work area 

MF operand = list, generate, or execute form parameters 
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Register = error return code (if register 1 5 indicates unsuccessful completion) 
Register = length of generated control blocks (if built in dynamically allocated 

storage obtained by VTAM and register 15 indicates successful 

completion) 
Register 1 ->■ generated control blocks (if built in dynamically allocated storage 

obtained by VTAM and register 15 indicates successful completion) 
Register 15 = general return code 

INQUIRE -> RPL: ACB field -» ACB 

( ECB field -> fullword work area ) 
\ EXIT field -> RPL exit-routine / 
OPTCD = (LOGONMSG|DEVCHAR|COUNTS|TERMS|BSCID|APPSTAT| 

CIDXLATE|TOPLOGON, SYN|ASY) 
If OPTCD = LOGONMSG, 

NIB field -> NIB: NAME field = symbolic name of terminal 

AREA field -» input area for logon message 

AREALEN field = length of input area 
If OPTCD = DEVCHAR, 

(NIB field -> NIB: NAME field = symbolic name of terminal) 

\ ARG field = CID of terminal J 

AREA field -> input area for characteristics 

AREALEN field = 8 
If OPTCD = TERMS, 

NIB field ->■ NIB: NAME field = symbolic name of terminal (or group, 
as defined by the GROUP definition macro) 

AREA field -> work area where NIBs will be built 

AREALEN field = length of work area 
If OPTCD = COUNTS, 

AREA field -* input area for data 

AREALEN field = 4 
IfOPTCD = APPSTAT, 

NIB field -> NIB : NAME field = symbolic name of application program 
If OPTCD = CIDXLATE, 

/NIB field -> NIB: NAME field = symbolic name of terminal) 

t ARG field = CID to be translated / 

AREA field -» input area for symbolic name 

AREALEN = 8 
If OPTCD = TOPLOGON, 

AREA field -> input area for symbolic name 

AREALEN = 8 
If OPTCD = BSCID, 

NIB field -> NIB: NAME field = symbolic name of UTERM terminal 

AREA field -> work area for ID verification sequence 

AREALEN field = 20 

Registers and 15 = return codes 

RPL: RECLEN field = length of data received (if RTNCD = and FDBK2 = 5 , 
RECLEN = total required length) 

FDBK field = status information (if OPTCD = APPSTAT) 

RTNCD field = recovery action return code 

FDBK2 field = specific error return code 

REQ field = request code 



Appendix A: Control Block Field Usage 165 



INTRPRET -► RPL: 



ACB fields ACB 

j NIB field -> NIB: NAME field = symbolic name of terminal ) 

\ ARG field = CID of terminal J 

AREA field -> data to be interpreted 

RECLEN field = length of data to be interpreted 

AAREA field -> work area for interpreted data 

AAREALN field = 8 

( ECB field -> fullword work area) 

\ EXIT field -+ RPL exit-routine j 

OPTCD field = SYNIASY 



Registers and 15 = return codes 

RPL: ARECLEN field = length of data received (if RTNCD = and FDBK2 = 5, 
ARECLEN = total required length) 

RTNCD field = recovery action return code 

FDBK2 field = specific error return code 

REQ field = request code 



MODCB AM = VTAM 

control block type operand -> control block 

control block field name operand = new value to be set 

MF operand = list, generate, or execute form parameters 



Register = error return code (if register 15 indicates unsuccessful completion) 
Register 15 = general return code 



OPEN 



-> ACB being opened 



Register 15 = return code 

ACB: OFLAGS field = opened or not-opened indicator 
ERROR field = specific error status information 

OPNDST -> RPL: ACB field -> opened ACB to which terminal is to be connected 

j ECB field -*• fullword work area ) 
\ EXIT field -> RPL exit-routine / 
OPTCD field = (SPECIANY, SYNIASY, CS|CA, Q|NQ, CONANY| 

CONALL, ACQUIREIACCEPT) 
NIB fields NIB: 

PROC field = processing options 

MODE field = BASIC or RECORD 

USERFLD field = data to be returned during subsequent 
I/O requests 
If OPTCD = ACQUIRE, 

NAME field = symbolic name of terminal 

LISTEND field = YES or NO 
If OPTCD = ACCEPT and ANY, 

NAME field not examined 

LISTEND field = YES 
If OPTCD = ACCEPT and SPEC, 

NAME field = symbolic name of terminal 

LISTEND field = YES 
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Registers and 15 = return codes 

RPL: ARG field = CID of connected terminal (but if CONALL in effect and 
more than one connected, unpredictable) 
RTNCD field = recovery action return code 
FDBK2 field = specific error return code 
REQ field = request code 
AREA field-* NIB: 

CID field = CID of connected terminal 

CON field = YES (if terminal connected) 

NAME field = symbolic name of connected terminal 

(when ACCEPT and ANY in effect) 
DEVCHAR field = device characteristics 

READ -> RPL: ACB field -> ACB 

ARG field = CID of source terminal 

AREA field -» input data area 

AREALEN field = length of input data area 

JECB field -> fullword work area 

t EXIT field -> RPL exit-routine 

OPTCD field = (SPEC|ANY, SYN|ASY, CS|CA) 

Registers and 15 = return codes 

RPL : ARG field = CID of source terminal (if OPTCD = ANY) 

RECLEN field = length of input data 

USER field = data from USERFLD field in NIB 

FDBK field = status information 

RTNCD field = recovery action return code 

FDBK2 field = specific error return code 

REQ field = request code 

RECEIVE -» RPL: ACB field -► ACB to which terminal connected 
ARG field = CID of terminal 
AREA field ->■ input data area 
AREALEN field = length of input data area 
BRANCH field = YES or NO 
$ ECB field -» fullword work area ) 
\ EXIT field -> RPL exit-routine f 
OPTCD field = (SYNIASY, CA|CS, SPEC|ANY, TRUNC|KEEP| 

NIBTK, Q|NQ) 
RTYPE field = (DFSYN|NDFSYN, DFASY|NDFASY, RESP|NRESP) 

Registers and 15 = return codes 

RPL: ARG field = CID of terminal completing the RECEIVE 
RTYPE field = type of input received 
RECLEN field = length of input data 
SEQNO field = sequence number of input 
RESPOND field = (EX|NEX, FME|NFME, RRN|NRRN) 
USER field = data from USERFLD field of NIB 
REQ field = request code 
RTNCD field = recovery action return code 
FDBK2 field = specific error return code 
CHNGDIR field = REQ|NREQ (if RTYPE = DFASY or RESP) 
CMDINCMD (if RTYPE = DFSYN) 
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BRACKET field = (BB|NBB, EB|NEB) 
CHAIN field = FIRST|MIDDLE|LAST|ONLY 
SIGDATA field = signal value (if CONTROL = SIGNAL) 
CONTROL field = DATA|QEC|RELQ|QC|CANCEL|CHASE|SHUTD| 

BID|LUS|SIGNAL|RTR|RSHUTD|SHUTC 
SSENSEI field = CPM|STATE|FI|RR|PATH|0 
SSENSMI field = system sense modifier value (or 0) 
USENSEI field = user sense value (or 0) 

RESET -* RPL: ACB field -> ACB 

ARG field = CID of terminal 
( ECB field -* full word work area) 
\ EXIT field -> RPL exit-routine J 
OPTCD field = (SYN|ASY, CS|CA, COND|UNCOND|LOCK) 

Registers and 15 = return codes 

RPL: USER field = data from USERFLD field in NIB 

RTNCD field = recovery action return code 

FDBK2 field = specific error return code 

REQ field = request code 

RESETSR -» RPL: ACB field -» ACB to which terminal connected 
ARG field = CID of receiving terminal 

( ECB field -> fullword work area) 

(EXIT field-* RPL exit-routine J 
BRANCH field = YES or NO 

RTYPE field = (DFSYNINDFSYN, DFASY|NDFASY, RESP|NRESP) 
OPTCD field = (SYNIASY, CA|CS) 

Registers and 15 = return codes 

RPL: USER field = data from USERFLD field in NIB 

RTNCD field = recovery action return code 

FDBK2 field = specific error return code 

REQ field = request code 

SEND -» RPL: ACB field -> ACB to which terminal connected 

ARG field = CID of receiving terminal 
AREA field ->■ data to be sent 
RECLEN field = length of data to be sent 
CHNGDIR field = REOJNREQ (if RTYPE = DFASY or RESP) 

CMDINCMD (if RTYPE = DFSYN) 
BRANCH field = YES or NO 
(ECB field -» fullword work area) 
\ EXIT field -» RPL exit-routine J 
RESPOND field = (EX|NEX, FME|NFME, RRN|NRRN) 
RTYPE field = (DFSYNINDFSYN, DFASY|NDFASY, RESP|NRESP) 
CONTROL field = DATA|QEC|RELQ|QC|CANCEL|CHASE|SHUTD| 

BIDILUS 
BRACKET field = (BB|NBB, EB|NEB) 
STYPE field = REQ or RESP 
IfSTYPE = RESP, 

SEQNO field = sequence number 
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If STYPE = RESP and RESPOND = EX, 
SSENSEO field = CPM|STATE|FI|RR 
SSENSMO field = system sense modifier value 
USENSEO field = user sense value 

If STYPE = REQ and CONTROL = DATA, 

CHAIN field = FIRST |MIDDLE| LAST I ONLY 
POST field = SCHEDIRESP (SCHED assumed if normal response 
not requested) 

Registers and 15 = return codes 

RPL: USER field = data from USERFLD field of NIB 

RTNCD field = recovery action return code 

FDBK2 field = specific error return code 

REQ field = request code 

SEQNO field = sequence number 

If POST = RESP and STYPE = REQ, 

CHNGDIR field = (REQINREQ, CMD|NCMD) 
RESPOND field = (EX|NEX, FME|NFME, RRN|NRRN) 
SSENSEI field = CPM|STATE|FI|RR|PATH|0 
SSENSMI field = system sense modifier value (or 0) 
USENSEI field = user sense value (or 0) 

SESSIONC -» RPL: ACB field -+ ACB to which terminal connected 

ARG field = CID of terminal 

/ ECB field -> fullword work area ) 

\ EXIT field -» RPL exit-routine J 

OPTCD field = SYNIASY 

CONTROL field = SDT|CLEAR|STSN 

IfCONTROL = STSN, 

IBSQVAL field = inbound sequence number 
IBSQAC field = SET|TESTSET|INVALID|IGNORE 
OBSQVAL field = outbound sequence number 
OBSQAC field = SET|TESTSET|INVALID|IGNORE 

Registers and 15 = return codes 

RPL: USER field = data from USERFLD field of NIB 

RTNCD field = recovery action return codes 

FDBK2 field = specific error return code 

REQ field = request code 

SSENSEI field = CPM | STATE |FI|RR|PATH|0 

SSENSMI field = system sense modifier value (or 0) 

USENSEI field = user sense value (or 0) 

IfCONTROL = STSN, 

IBSQVAL field = inbound sequence number 
IBSQAC field = TESTPOS|TESTNEG|RESET|INVALID 
OBSQVAL field = outbound sequence number 
OBSQAC field = TESTPOS|TESTNEG|RESET|INVALID 

SIMLOGON -> RPL: ACB field -» ACB 
NIB field -> NIB: 

NAME field = symbolic name of terminal 

LISTEND field = YES or NO 
AREA field -> logon message 
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RECLEN field = length of logon message 

( ECB field -> fullword work area) 

\ EXIT field -> RPL exit-routine J 

OPTCD field = (SYNIASY, Q|NQ, CONANY|CONALL) 

Registers and 15 = return codes 

RPL: RTNCD field = recovery action return code 

FDBK2 field = specific error return code 

REQ field = request code 



SOLICIT -> RPL: ACB field -» ACB 

ARG field = CID of source terminal (if OPTCD = SPEC) 

( ECB field -*■ fullword work area) 

(EXIT field-* RPL exit-routine J 

OPTCD field = (SPECIANY, SYN|ASY, CS|CA) 

Registers and 15 = return codes 

RPL: USER field = data from USERFLD field of NIB 

RTNCD field = recovery action return code 

FDBK2 field = specific error return code 

REQ field = request code 

TESTCB AM = VTAM 

control block type operand -» control block 

field name operand = test value 

ERET operand -* error exit-routine 

MF operand = list, generate, or execute form parameters 

Register = error return code (if register 15 indicates unsuccessful completion) 
Register 15 = general return code 
PSW condition code = test result 

WRITE -> RPL: ACB field ^ACB 

ARG field = CID of receiving terminal 
AREA field -» data to be written 
RECLEN field = length of data to be written 
AAREA field -» input data area 
AAREALN field = length of input data area 
j ECB field -> fullword work area) 
\ EXIT field -*- RPL exit-routine J 

OPTCD field = (SYNIASY, CS|CA, BLK|LBM|LBT, CONV|NCONV, 
ERASE|EAU|NERASE) 

Registers and 1 5 = return codes 

RPL: ARECLEN field = length of input data 

USER field = data from USERFLD field of NIB 

FDBK field = status information 

RTNCD field = recovery action return code 

FDBK2 field = specific error return code 

REQ field = request code 
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APPENDIX B. LINE-CONTROL CHARACTERS RECOGNIZED 
OR SENT BY VTAM MACRO INSTRUCTIONS 



This appendix is only for programmers who are concerned with communication 
between the application program and BSC or start -stop terminals. Communication 
with logical units does not involve line-control characters. 

VTAM relieves the application program of the task of inserting line-control 
characters into outgoing data and removing line-control characters from incoming 
data. The application program, however, is not completely line-control independ- 
ent. For an output operation, the BLK-LBM-LBT option for the WRITE macro 
instruction governs which line-control characters are inserted in the data. For a 
solicit operation, the BLOCK-MSG-TRANS-CONT option identifies the line-control 
character that causes solicitation to stop when that character is received. The 
application programmer must be aware of the effect of these options. 

The first three columns in Figures B-l and B-2 show the line-control characters that 
delimit the data obtained by a solicit operation. The first column shows the 
delimiting character when the NIB's BLOCK-MSG-TRANS-CONT processing option 
is set to BLOCK, the second column shows the delimiting character when the 
processing option is set to MSG, and the third shows the delimiting character when 
TRANS is in effect. (There are no delimiting characters for CONT, because 
solicitation continues indefinitely.) 

The last three columns show the line-control characters added to the beginning and 
end of the user-supplied data when a WRITE macro instruction is issued. The first 
of these three columns shows the beginning and ending characters that are inserted 
when the RPL's option code is set to BLK, or if a WRITE LDO is being used by 
DO. The next shows the characters inserted when the LBM option code is in effect 
or a WRITELBM LDO is used. The last column applies to the LBT option code or 
WRITELBT LDO. 
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Soliciting 


Writing 




Specified as PROC = 

BLOCK TDAMC 


(b) = inserted at the 
beginning 

(e) = inserted at end 


Start— Stop Devices 




MSG 




Specil 
BLK 


Fied as OPTC 
LBM 


:d = 

LBT 


IBM 1050 Data Communication System 


EOB 


EOT 


EOT 


EOA(b) 
EOB(e) 


EOA(b) 
EOB(e) 1 


EOA(b) 
EOB(e) 1 


IBM 2740 Communication Terminal, Model 1 


EOT 


EOT 


EOT 


EOA(b) 
NUL(e) 


EOA(b) 
NUL(e) 


EOA(b) 
NUL(e) 


IBM 2740 Communication Terminal, Model 1, 
with checking 


EOB 


EOT 


EOT 


EOA(b) 
EOB(e) 


EOA(b) 
EOB(e) 1 


EOA(b) 
EOB(e) 1 


IBM 2740 Communication Terminal, Model 1, 
with checking and station control 


EOB 


EOT 


EOT 


EOA(b) 
EOB(e) 


EOA(b) 
EOT(e) 


EOA(b) 
EOT(e) 


IBM 2740 Communication Terminal, Model 2 


EOT 


EOT 


EOT 


EOA(b) 
EOT(e) 1 


EOA(b) 
EOT(e) 1 


EOA(b) 
EOT(e) 1 


IBM 2741 Communication Terminal 


EOT 


EOT 


EOT 


EOA(b) 
NUL(e) 


EOA(b) 
NUL(e) 


EOA(b) 
NUL(e) 


IBM Communication Magnetic Card 
Selectric Typewriter 


EOT 


EOT 


EOT 


EOA(b) 
NUL(e) 


EOA(b) 
NUL(e) 


EOA(b) 
NUL(e) 


IBM World Trade Telegraph Station 


EOT 


EOT 


EOT 


CCITT 
header 


CCITT 
header 


CCITT 
header 


IBM SYSTEM/7 


EOT 


EOT 


EOT 


EOA(b) 
NUL(e) 


EOA(b) 
NUL(e) 


EOA(b) 
NUL(e) 


AT&T 83B3 Selective Calling Station 


EOT 


EOT 


EOT 


none(b) 
EOM(e) 


none(b) 
EOM(e) 


none(b) 
EOM(e) 


AT&T Teletypewriter Terminal, Models 
33 and 35 


EOT 


EOT 


EOT 


none(b) 
EOM(e) 


none(b) 
EOM(e) 


none(b) 
EOM(e) 


Western Union Plan 1 15A Station 


EOT 


EOT 


EOT 


none(b) 
EOM(e) 


none(b) 
EOM(e) 


none(b) 
EOM(e) 




1 

And an EOT is sent when the block is 
acknowledged by the system with a 
positive response. 



Figure B-l. Line-Control Characters Used With Start-Stop Devices 
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Soliciting 


Writing 




Specif 
BLOCK 


ed asPROC = 

i 

TD AMC 


(b) = inserted at the 

beginning 
(e) = inserted at end 


Binary Synchronous Communication Devices 


MSG 




Specified as OPTCD = 
BLK LBM LBT 


IBM 2770 Data Communication System 


ETB 


ETX 


EOT 


STX(b) 
ETB(e) 


STX(b) 
ETX(e) 


STX(b) 
ETX(e) 1 


IBM 2780 Data Transmission Terminal 


ETB 


ETX 


EOT 


STX(b) 
ETB(e) 


STX(b) 
ETX(e) 


STX(b) 
ETX(e) 1 


IBM 2972 General Banking Terminal, 
Models 8 and 1 1 


ETB 


ETX 


EOT 


STX(b) 
ETX(e) 


STX(b) 
ETX(e) 


STX(b) 
ETX(e) 1 


IBM 3270 Information Display System, 
remotely attached 


2 


EOT 


EOT 


2, 3 


3 


STX(b) 
ETX(e) 3 


IBM 3735 Programmable Buffered Terminal 


ETB 


ETX 


EOT 


STX(b) 
ETB(e) 


STX(b) 
ETX(e) 


STX(b) 
ETX(e) 1 


IBM 3740 Data Entry System 


ETB 


ETX 


EOT 


STX(b) 
ETB(e) 


STX(b) 
ETX(e) 


STX(b) 
ETX(e) 1 


IBM 3780 Data Transmission Terminal 


ETB 


ETX 


EOT 


STX(b) 
ETB(e) 


STX(b) 
ETX(e) 


STX(b) 
ETX(e) 1 


IBM SYSTEM/3 


ETB 


ETX 


EOT 


STX(b) 
ETB(e) 


STX(b) 
ETX(e) 


STX(b) 
ETX(e) 1 


IBM SYSTEM/370 


ETB 


ETX 


EOT 


STX(b) 
ETB(e) 


STX(b) 
ETX(e) 


STX(b) 
ETX(e) 1 




1 

And an EOT is sent when the block 
is acknowledged by the system with 
a positive response. 

2 PROC=BLOCK and OPTCD=BLK are 
invalid for 3270 devices. 

3 

No line control characters are sent. 



Figure B-2. Line-Control Characters Used With BSC Devices 
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APPENDIX C. RETURN CODES FOR RPL-BASED MACRO INSTRUCTIONS 

Return Code Posting VTAM posts return code information in registers and 15 and in certain fields of 

the request's RPL. These fields are referred to as the feedback fields. The manner in 
which registers 0, 15, and the feedback fields are posted depends on whether 
synchronous request handling, asynchronous request handling (with an ECB), or 
asynchronous request handling (with an RPL exit-routine) is used. Chapter 5 of 
VTAM Concepts and Planning illustrates these three methods of request handling. 
The following three figures parallel those in the Concepts book (although the 
posting of register 1 5 and feedback fields has been emphasized here). 

In Figure C-l, the application program issues a SEND macro instruction and 
specifies synchronous request handling. Control passes from the application 
program and is not returned until the operation is completed. At that time, registers 
and 15 are set by VTAM (or, if the LERAD or SYNAD exit-routine is scheduled, 
registers and 15 are set by the exit-routine) to indicate how the operation is 
completed. Feedback fields in the RPL are also set. 

In Figure C-2, the application program issues another SEND, this time specifying 
asynchronous request handling and an ECB. VTAM receives control, screens the 
request, schedules the requested operation (if the request is in order), and returns 
control to the application program. If the request was unacceptable, VTAM (or the 
LERAD or SYNAD exit-routine, if one was available to be scheduled) indicates this 
in registers and 15. No additional return codes are posted in RPL2's feedback 
fields, and no CHECK macro instruction should be issued for RPL2. (The RPL is 
not set active if the request is not accepted, and CHECK cannot be used to check 
an inactive RPL.) 

The application program will find a return code of in register 15 if the request 
was accepted. Since an ECB was specified for the request, the application program 
must eventually issue a CHECK macro instruction for RPL2. (A system WAIT 
macro instruction could be used instead, although CHECK would still be required 
eventually to set the RPL inactive.) When the SEND operation is eventually 
completed, the ECB is posted and control is again returned to the application 
program. This time registers and 1 5 and RPL2's feedback fields are set by VTAM 
(or by the LERAD or SYNAD exit-routine, if one was invoked) to indicate how the 
SEND operation was completed. 

Application Program VTAM 



SEND I RPL=RPL1,OPTCD=SYN 



Request is accepted 
(LERAD or SYNAD 
exit-routine scheduled, 
if not excepted) 



SEND is completed 
(LERAD or SYNAD exit- 



• Registers and 15 and routine scheduled, if 

• RPL fields posted by VTAM appropriate) 

• or by exit-routine 

Figure C-l. Posting Return Codes for Synchronous Requests 

Appendix C: Return Codes for RPL-Based Macros 175 



Application Program VTAM 



SEND 



RPL=RPL2,OPTCD=ASY, 
ECB=FULLWORD 

► 



Request is accepted 
(LERAD or SYNAD exit- 
Registers and 15 posted by routine scheduled, if not 
VTAM (or by exit-routine) accepted) 



interruption 



SEND is completed 



ECB is posted 



CHECK ECB (LERAD or SYNAD exit-routine 

(or WAIT) scheduled, if appropriate) 

Registers and 15 and 
RPL posted 



Figure C-2. Posting Return Codes for Asynchronous Requests (with CHECK) 

In Figure C-3, the application program again issues an asynchronous SEND request, 
but this time with an RPL exit-routine specified instead of an ECB. As before, a 
zero or non-zero return code is returned to the application program, indicating that 
the request has been accepted or rejected. The completion of the SEND operation 
results in the invocation of the RPL exit-routine if the request was accepted. After 
CHECK has been issued, EXITRTN finds that registers and 15 and the feedback 
fields of RPL3 have been posted. 

Types of Return Codes VTAM always sets register 15 to to indicate that a request has been accepted or 

has been completed normally. Register is also sometimes set for normal 
completion, as noted below. 

When a request is not accepted or is completed abnormally, VTAM schedules the 
LERAD or SYNAD exit-routine. (Figures C-4 and C-5 indicate which types of 
errors cause LERAD and which cause SYNAD to be scheduled.) If the LERAD or 
SYNAD exit-routine is executed upon return of control to the next sequential 
instruction registers and 15 contain whatever values were placed in them by the 
exit-routine. If VTAM cannot find an exit to schedule then it sets registers and 15 
and returns control to the next sequential instruction. 
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Application Program 



VTAM 



SEND 



RPL=RPL3,0PTCD=ASY, 
EXIT-EXITRTN 



Registers and 15 posted 
by VTAM (or by exit-routine) 



interruption 



EXITRTN 



• 

CHECK 

RPL-RPL3 

• 



Request is accepted 
(LERAD or SYNAD exit- 
routine scheduled if not 
accepted) 



SEND is completed, 
RPL exit-routine is 
scheduled, RPL is posted 



(LERAD or SYNAD exit-routine scheduled, if 
appropriate) Registers and 15 posted 



Control is returned 



Figure C-3. Posting Return Codes for Asynchronous Requests (with an RPL 
Exit-Routine) 

VTAM uses only two nonzero return codes in register 15:4 and 32 (decimal). 32 is 
used when a failure of an OPEN is ignored by the application program; neither 
SYNAD nor LERAD are involved. A return code of 4 is used for all other types of 
errors. The register 15 return code is termed a general return code. 

The "other types of errors" are organized into 6 classes according to the program 
recovery action that is appropriate for each error. VTAM generates a recovery 
action return code for each class and places the code in register when control is 
returned to the application program or passed to the LERAD or SYNAD 
exit-routine. VTAM also posts the recovery action return code in the RTNCD field 
of the RPL. The recovery action return codes occur in increments of 4 to facilitate 
their use in branching tables. 

Note: The recovery action return code is posted when the request's ECB is posted; 
if you modify RTNCD before checking the request, VTAM does not reset the code. 
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3 1 

to' 
>-» 

O 

o 
o 



o 

S3 

o 
o 

3 

8*. 
o 

3 

> 

H. 

o" 
cT 



n 
o 



•« 



<< 

S3 
o 

13* 

l-t 
O 

S3 
O 

5* 
a> 

C 

CD 



Completion 
Condition 


Explanation 


Example 


Registers when 
SYNAD-LERAD 
not available 


Registers when 
SYNAD-LERAD 
are available 


RPL 

feedback 
fields set 


Applicable 
macros 


Recommended 
Programmer Action 
(in LERAD, SYNAD, 
or after next 
sequential instruction 


Request accepted 
(General return code 
= 0, Recovery action 
return code = 0) 


VTAM has accepted the 
asynchronous request 
and will process it. Com- 
pletion information will 
again be available when 
the request is completed. 




Reg 15 Reg 



Reg 15 Reg 



(LERAD-SYNAD 
not entered) 


RTNCD=0 
FDBK2=0 


All RPL- 
based macros 








Request not 
accepted (General 
return code = 4), 
Retry Appropriate 
(Recovery action 
return code = 8) 

Environment Error 
(Recovery action 
return code = 16) 

Logical Error 
(Recovery action 
return code = 20) 

Logical Error 
with Invalid RPL 
(Recovery action 
return code = 24) 


VTAM has rejected the 
asynchronous request 
because of a temporary 
condition. 

VTAM has rejected the 
asynchronous request be- 
cause of an environment- 
al condition beyond the 
control of the application 
program. 

VTAM has rejected the 
asynchronous request be- 
cause the request violates 
the requirements defined 
in this manual. 

VTAM has rejected the 
asynchronous request be- 
cause the RPL address 
points to an active RPL 
or does not point to any 
RPL. 


A temporary 
storage 
shortage has 
occurred. 

VTAM not 
active. 

A READ has 
been issued 
for an output- 
only device. 

An attempt 
was made to 
reuse an RPL 
to which no 
CHECK had 
been issued. 


Reg 15 Reg 
4 8 

Reg 15 Reg 
4 16 

Reg 15 Reg 
4 20 

Reg 15 Reg 
4 24 


Reg 15 Reg 

Set by SYNAD 
exit-routine 

Reg 15 Reg 

Set by SYNAD 
exit-routine 

Reg 15 Reg 

Set by LERAD 
exit-routine 

Reg 15 Reg 

Set by LERAD 
exit-routine 


RTNCD=8, 
FDBK2= 
specific 
error 
return code 

RTNCD=16, 
FDBK2= 
specific 
error 
return code 

RTNCD=20, 
FDBK2= 
specific 
error 
return code 

RPL not set 
and should 
not be 
examined. 


All RPL- 
based macros 

All RPL- 
based macros 

All RPL- 
based macros 

All RPL- 
based macros 


Issue an EXECRPL 
macro to retry the 
request. 

Request external 
intervention (from 
the network operator, 
for example) or 
suspend processing. 

Obtain a program 
dump and correct the 
program. 

Obtain a program 
dump and correct the 
program. 


Request not accepted 
because of a prior 
failure OPEN 
(General return code 
= 32, no Recovery 
action return code) 


The RPL points to an 
ACB that has not been 
properly opened or that 
has been closed. 




Reg 15 Reg 

32 Request 
code (see 
descript- 
ion of 
RPL's 
REQ field) 


Reg 15 Reg 

32 Request 
code (see 
descript- 
ion of 
RPL's 
REQ field) 

(LERAD-SYNAD 

not entered) 


RPL not 
set. 


All RPL- 
based macros 


Obtain a program 
dump and correct the 
program. 





2 



















Recommended 


















Programmer Action 










Registers when 


Registers when 


RPL 




(in LERAD, SYNAD, 




Completion 






SYNAD-LERAD 


SYNAD-LERAD 


feedback 


Applicable 


or after next 


Ti 


Condition 


Explanation 


Example 


not available 


are available 


fields set 


macros 


sequential instruction 


C 
CD 


Normal Completion 


The request has been 


INQUIRE 


Reg 15 Reg 


Reg 15 Reg 


RTNCD=0, 


All RPL- 


RESET, WRITE, 


o 


(General return code 


completed successfully. 


was issued to 


Additional 


Additional 


FDBK2= 


based macros 


INQUIRE, INTRPRET, 


V) 


= 0) 


For some macros (see 


obtain a logon 


informa- 


informa- 


Additional 




OPNDST, RECEIVE, 


p 




right-most column), 


message, and 


tion return 


tion return 


information 




and SIM LOGON 


•-* 

rt- 




Register contains add- 


there was 


code 


code 


return code 




macros can be complet- 


i— 




itional information. 


none. 










ed normally with special 


o 










(LERAD-SYNAD 






conditions present. If 


to 










not entered) 






these conditions are 


2 n 

H o 
















meaningful to the appli- 
















cation program, check 


















Register or FDBK2. 


o S* 
















These conditions are 


2§ 
















explained after Fig. C-6. 


«9 


Abnormal Completion 


















(General return code 


















= 4), 
















O 

fcJ 

CO 


Special Condition 


The terminal has re- 


An exception 


Reg 15 Reg 


Reg 15 Reg 


RTNCD=4, 


OPNDST, 


Take whatever action is 


> 
*T3 


(Recovery action 


turned a special cond- 


message has 


4 4 


Set by SYNAD 
exit-routine 


FDBK2= 


DO, READ, 


appropriate for the 




return code = 4) 


ition indicator for a 


been received. 




special 


WRITE, 


FDBK2 indicator. 


o 




request that would 








condition 


SEND, and 


These indicators are 


<r 




otherwise have been 








indicator 


RECEIVE 


explained after Fig. C-6. 


CD* 

o 1 




completed normally. 














l-t 
("5 


Retry Appropriate 


VTAM cannot com- 


A temporary 


Reg 15 Reg 


Reg 15 Reg 


RTNCD=8, 


All RPL- 


Issue an EXECRPL 


o 
3 
"EL 


(Recovery action 


plete the request be- 


storage 


4 8 


Set by SYNAD 
exit-routine 


FDBK2= 


based macros 


macro to retry the 


return code = 8) 


cause of a temporary 


shortage has 




specific 




request. 


co" 




condition. 


occurred. 






error 






o* 












return code. 






O 


Data Integrity 


VTAM cannot com- 


A hardware 


Reg 15 Reg 


Reg 15 Reg 


RTNCD=12, 


OPNDST, 


Take whatever action is 


t/3 


Damaged 


plete the request. Either 


error occurred 


4 12 


Set by SYNAD 
exit-routine 


FDBK2= 


CHANGE, 


appropriate to the 




(Recovery action 


the data itself has been 


during an 




specific 


and all I/O 


FDBK2 return code. 


ST 


return code = 12) 


lost and must be resent. 


output oper- 






error 


macros 


These codes are ex- 


o 




or the output medium 


ation. 






return code 




plained after Fig. C-6. 


O 




(the form in a printer, 












In general, the process 




for example)has been 












that was interrupted 






overwritten and the 












should be restarted. 


£2 




operation must be 














0) 

CO 




redone. 















to' 
















Recommended 


CD 
















Programmer Action 


n 
i 








Registers when 


Registers when 


RPL 




(in LERAD, SYNAD, 


en 


Completion 






SYNAD-LERAD 


SYNAD-LERAD 


feedback 


Applicable 


or after next 


p 


Condition 


Explanation 


Example 


not available 


are available 


fields set 


macros 


sequential instruction 




Abnormal Completion 
















o 

1-^ 


(General return code 


















= 4), (Cont.) 
















8 P 


Environment Error 


VTAM cannot complete 


VTAM not 


Reg 15 Reg 


Reg 15 Reg 


RTNCD=16, 


All RPL- 


Take whatever action is 


^ O 


(Recovery action 
return code = 16) 


the request. The prob- 
lem cannot be resolved 
without external 


active. 


4 16 


Set by SYNAD 
exit-routine 


FDBK2= 

specific 

error 


based macros 


appropriate for the 
FDBK2 return code. 
These codes are ex- 






intervention. 








return code 




plained after Fig. C-6. 
















In general, the terminal 


3 
















is unavailable and 


O* 
















should either be discon- 


o' 
















nected or network oper- 


1/1 
















ation intervention 


> 
















should be requested. 




Logical Error 


VTAM cannot complete 


An I/O 


Reg 15 Reg 


Reg 15 Reg 


RTNCD=20, 


All RPL- 


Obtain a program dump 


p 
cr 


(Recovery action 


the request because it 


request is 


4 20 


Set by LERAD 
pxit-rnutinp 


FDBK2= 


based macros 


and correct the program. 


?T 


return code = 20) 


violates the requirements 


issued for a 




specific 






Q 




defined in this manual. 


disconnected 




CAI 1 1 UULIIIV/ 


error 






n 






terminal. 






return code 






o 
3 


Logical Error with 


VTAM cannot complete 


The RPL 


Reg 15 Reg 


Reg 15 Reg 


RPL not set 


All RPL- 


Obtain a program dump 




Invalid RPL 
(Recovery action 


the request because the 
RPL address points to 


address was 
destroyed 


4 24 


Set by LERAD 

PYit-rm itinp 


and should 
not be 


based macros 


and correct the program. 


o 

13 


return code = 24) 


an active RPL or does 


before the 




CA1L 1 UUIMIC 


examined. 






O 




not point to any RPL. 


request was 












on 
<< 






executed. 












3 
o 


Abnormal Completion 


VTAM cannot complete 




Reg 15 Reg 


Reg 15 Reg 


RPL not 


All RPL- 


Obtain a program dump 


o 


because of a prior 


the request because the 




32 Request 
code (see 
description 
of RPL's 
REQ field) 


32 Request 
code 


set. 


based macros 


and correct the program. 


o 


OPEN failure (Gener- 


RPL points to an ACB 










00 
00 


al return code = 32, 
no Recovery action 
return code). 


that has not been prop- 
erly opened or that has 
been closed. 




(LERAD-SYNAD 
not entered) 









VTAM also generates a specific error return code that defines the exact type of 
error within the recovery action category. The specific error return code is placed 
by VTAM into the FDBK2 field of the RPL. 

These return codes do not occur in increments of 4; multiply them by 4 if a 
branching table is to be used. The specific error return codes are described after 
Figure C-6. 

To summarize: 

• There are 3 general return codes: (normal), 4 (abnormal, LERAD or SYNAD 
not accessible to VTAM), and 32 (abnormal, failure to detect prior OPEN 
failure). 

• There are 6 recovery action return codes that apply for abnormal completion. 
These are posted in the RTNCD field of the RPL and in register 0. If LERAD or 
SYNAD are invoked, the exit-routine can return its own register and 15 values 
to the next sequential instruction. 

• There are numerous specific error return codes that apply for abnormal 
completion. These are posted in the FDBK2 field. 

Specific Error Return Codes The return code set in the FDBK2 field is meaningful only when it is considered 

(FDBK2) together with the recovery action return code in the RTNCD field. 

You can determine the setting of the RTNCD or FDBK2 fields with either the 
SHOWCB or TESTCB macro instructions. For example: 

SHOWCB AM=VTAM,RPL=RPL1 ,FIELDS=(RTNCD,FDBK2), 
AREA=WORKAREA,LENGTH=8 

Since both RTNCD and FDBK2 have been specified in the FIELDS operand, both 
fields will be copied into WORKAREA. Note that WORKAREA is 8 bytes long. 
SHOWCB right-justifies each field in the fullword that you supply, and sets the first 
3 bytes to 0. Since two fields are being used in this example, a 2-fullword work area 
is required. 

A TESTCB macro instruction might look like this: 
TESTCB AM=VTAM,RPL=RPL1 ,RTNCD= 12 

The feedback fields must be tested serially, since TESTCB works only with one 
control block field at a time. Thus another TESTCB macro instruction would be 
required to test the contents of the FDBK2 field. 

Figure C-6 shows the RTNCD-FDBK2 combinations that are valid for a given macro 
instruction. Only the RPL-based macro instructions are included, since feedback 
posting applies only to RPL-based macro instructions. CHECK and EXECRPL are 
not shown because all of the indicated RTNCD-FDBK2 combinations are possible 
upon return from them. 

Although specific error return codes apply only when RTNCD contains a nonzero 
recovery action code, this figure includes some FDBK2 values for RTNCD=0. These 
are additional information codes that apply to certain normally-completing 
requests. These codes are explained in the text following Figure C-6. 

The horizontal lines in Figure C-6 do not imply any logical grouping; they have 
been inserted simply for legibility. 
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Once you have used Figure C-6 to determine which RTNCD-FDBK2 combinations 
are possible for a particular macro instruction, refer to the return code descriptions 
below for an explanation of each RTNCD-FDBK2 combination. 

Should you detect a return code during program execution other than one 
described in these figures, you should cease attempting to communicate with the 
terminal. You may wish to use SHOWCB macro instructions to extract the contents 
of the RPL fields, and you should obtain a program dump. Save your source listings 
and any program execution output for IBM program systems representatives. 

RTNCD FDBK2 

Normal completion or request accepted 

The operation has been completed normally or the request has been accepted. 

1 RESET (COND) issued with I/O in progress 

You issued a conditional RESET (OPTCD=COND), and since an I/O operation for 
the terminal had already reached the data transfer stage, the I/O operation has not 
been canceled. 

2 Normal completion with data 

A RESET (OPTCD=COND) macro instruction was completed normally, but 
solicited data from the terminal already resides in VTAM's buffers. This data should 
be obtained with READ macro instructions. 

12 (X'OC) 14 (X'OE') Yielded to contention 

You attempted to write to a terminal on a point-to-point contention line at the 
same time that the terminal attempted to gain control of the line. The system 
yielded the line to the terminal, and your output operation has been canceled. 

12 (X'OC) 15 (X'OF') Yielded to contention (no lock set) 

Following connection, you attempted to write to a terminal on a point-to-point 
contention line at the same time that the terminal attempted to gain control of the 
line. The system yielded the line to the terminal, and your output operation has 
been canceled. The error lock is set; issue RESET before attempting further 
communication. 

5 Input area too small 

You issued INQUIRE or INTRPRET and specified an input work area that is too 
small. VTAM has placed the reuired length (in bytes) in the RPL's RECLEN field. 
No data has been placed in the work area. 

Obtain a work area that is at least as long as the value set in RECLEN, place the 
length in the AREALEN field, and reissue INQUIRE or INTRPRET. 

6 No input available 

A RECEIVE with OPTCD=NQ was issued and there was no input of the specified 
RTYPE available to satisfy the macro instruction. 

7 INQUIRE information not available 

You issued INQUIRE (OPTCD=LOGONMSG) to obtain a logon message, and there 
is none, you issued INQUIRE (OPTCD=TERMS) for a particular TERMINAL, 
LINE, or GROUP entry in the resource definition table, and that entry cannot be 
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found, you issued INQUIRE (OPTCD=TOPLOGON) for queued logon requests, 
and there are none, or you issued INQUIRE (OPTCD=CIDXLATE) for a terminal 
that has not been connected. 

The problem may be due to an incorrectly set NAME field in the NIB, a failure on 
the part of the installation to create the entry during VTAM definition, or a VARY 
command issued by the network operator that deactivated the entry. 

RTNCD FDBK2 

8 OPNDST (ACQUIRE) denied terminal in use 

You attempted to acquire a terminal; the terminal is connected to another 
application program, and so the request is rejected. 

9 OPNDST (ACCEPT) denied-no logon requests 

You attempted to accept a terminal, and you indicated that your request should be 
rejected if no terminal is waiting to be accepted (OPTCD=NQ). There is no logon 
request queued for your 'application program, and so the request is rejected. 

4 RVI received 

The terminal responded to your output operation with an RVI (reverse interrupt) 
response. When this response is received, an error lock is set for the terminal. RVIs 
apply only to binary synchronous devices. 

4 1 Attention or reverse break received 

The termini either responded to your output operation with an attention 
interruption or reverse break, or terminated its transmitted data with an attention 
interruption or reverse %reak. This bit is set only for 2741 Communication 
Terminals and 1050 Data Communication System Terminals. 

When the attention interruption or reverse break is detected, an error lock is set for 
the terminal. 

4 2 SENSE field set 

The RPL's SENSE field has been set because a sense/status message has been 
received from a BSC device. Near the end of this appendix there is a brief 
description of the type of information ^provided in the SENSE field. You must refer 
to the component description manual of each terminal for an explantion of this 
information. 

4 3 Exception condition for incoming message 

A -message has been received lor Which an exception condition exists. The reason 
for the error is contained in the RPLVSSENSEI and SSENSMI fields. All messages 
in the current chain that have already been received by the application program 
should be discarded. Issue RECEIVE macros with OPTCD=TRUNC, AREALEN=0 
until CHAIN-LAST or CONTROL-CANCEL is received. No responses should be 
sent for any element in the rest of the chain. If an exception response has not 
already been sent to an element of this chain, move the input sense fields to the 
output sense fields and send an exception response . 

4 4 Incoming response indicates exception condition 

The terminal has sent a response indicating that an exception condition was 
detected for one of the messages the 'application program sent to it. The SEQNO 
field indicates the sequence number of the message to which the exception response 
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applies. The SSENSEI and SSENSMI (or the USENSEI) fields indicate the reason 
for the error condition. 

If the message is part of the chain currently being transmitted to the terminal, the 
application program should issue a SEND with STYPE=REQ, CONTROL=DATA, 
and CHAIN=LAST or a SEND with STYPE=REQ and CONTROL=CANCEL to 
indicate where the terminal can stop discarding the messages it has been receiving. 
If the sequence numbers need to be reset (back to the beginning of the chain, for 
example) a SESSIONC with CONTROL=STSN should be issued. Use SESSIONC 
with CONTROL=CLEAR or SEND with CONTROL=CHASE before resetting the 
sequence number. 

RTNCD FDBK2 

8 Temporary storage shortage 

VTAM is temporarily unable to secure enough storage to process the request. The 
request can be reissued (with EXECRPL, for example). 

12 (X'OC) Error lock set 

An error lock has been set for the device that is the object of the I/O request. The 
SENSE field may contain status/ sense information (if it does not, the field will be 
set to 0). 

Error locks are set by the operating system or by the communication controller's 
Network Control Program when an I/O error condition is detected that prevents 
successful completion of the operation. 

When an error lock is set for a terminal, no further I/O can be accomplished until 
the error lock is reset with a RESET macro instruction. If I/O requests are issued 
while the error lock is utill set, they will remain pending until RESET is finally 
issued. 

Two forms of RESET (OPTCD=UNCOND and OPTCD=LOCK) cause the error lock 
to be reset. You may prefer to use the LOCK form, which resets the error lock 
without canceling any pending I/O requests you may have issued since the error 
lock was set, or that have been queued since the error lock was set. 

12 (X'OC) 1 Terminal not usable 

This code is set when the communications controller detects either a hardware 
check for the terminal or a modem check for the terminal's modem, or when the 
dial-line disconnection occurs for a dial-in terminal. Hardware and modem checks 
are discussed in IBM 3704 and 3705 Communications Controller Principles of 
Operation, GC30-3004. In general, this return code means that the terminal is no 
longer usable and should be disconnected. 

12 (X'OC) 2 Request canceled by test request message 

This I/O operation has been canceled because the terminal operator requested 
connection to the Teleprocessing Online Test Executive Program (TOLTEP). The 
terminal must be disconnected (CLSDST with OPTCD=RELEASE). Any further 
attempts to communicate with the terminal will be rejected by VTAM. You should 
reestablish connection with the terminal in the same manner in which the 
connection was initially established— either by acquiring the terminal or by 
accepting it. 

12 (X'OC) 3 Buffer now emptied 

Prior to the receipt of this return code, VTAM's input buffers for the terminal were 
exhausted. The input request that empties the final block of data from the buffer 
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receives this return code. You may now continue communicating normally with the 
terminal. Refer also to the explanation for RTNCD=12 and FDBK2=4 which 
follows. 

RTNCD FDBK2 

12(X'0C) 4 Buffers filled 

Solicited data has exhausted VTAM's buffers. All I/O operations other than READ 
are invalid until the buffers have been emptied. To empty the buffers, reissue 
READ macro instructions until RTNCD=12 and FDBK2=3 (buffers now emptied) 
is returned; this indicates that the last block of data has been moved into the 
application program. 

It is possible that you are soliciting too large a unit of data— for example, you are 
soliciting a transmission, but the installation expected that you would never solicit 
more than a block at a time. Even the smallest unit of data (block) may be too 
large, and the only solution is for the installation to enlarge VTAM's buffer size. 

The second general cause of this error is that you are not emptying VTAM's buffers 
at a rate approximately equal to the rate that the data is arriving. You may be 
issuing new SOLICIT requests without first verifying that you have obtained the 
last block of the previously solicited data. 

12 (X'OC) 5 NCP abended, restart successful 

While your request was being processed, the communications controller's Network 
Control Program abnormally terminated. It has been successfully restarted, and you 
can reissue your request and continue. All affected I/O requests except the last one 
receive this return code (the last I/O request issued before the NCP abended 
receives a FDBK2=6 return code). 

12 (X'OC) 6 NCP abended, restart successful (final I/O request) 

While this request was being processed, the communications controller's NCP 
abended and was successfully restarted. This is the last I/O request to be canceled 
because of the abend. The application progarm should either (1) issue RESET 
(OPTCD=LOCK) to allow other pending I/O requests for this terminal to proceed 
normally, or (2) issue RESET (OPTCD=UNCOND) to cancel all other pending I/O 
requests so that the application program can reissue them again in sequence. 

12 (X'OC) 7 Connection recovery in progress 

Contact with the logical unit has been lost. If a LOSTERM exit-routine is available, 
it has been scheduled. No further communication with this terminal is possible until 
the terminal has been reconnected. Reconnection occurs automatically; the 
LOSTERM exit-routine is rescheduled when the reconnection occurs. 

12 (X'OC) 8 Logical unit restarted 

The terminal has experienced a failure but loss of contact has not occurred. 
However, the terminal has in effect been disconnected from your application 
program. Issue CLSDST to complete the disconnection process. No RECEIVE 
macro instructions should be attempted prior to the disconnection. OPNDST may 
be attempted following the CLSDST. The application program is also informed of 
this condition via the LOSTERM exit-routine. 

12 (X'OC) 10 (X'OA') Request canceled by RESET or RESETSR 

This I/O operation has been canceled by a RESET or RESETSR macro instruction 
issued by another part of your application program. 
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RTNCD FDBK2 

1 2 (X'OC) 1 1 (X'OB') Request canceled by CLSDST 

The I/O operation has been canceled because you disconnected the terminal after 
issuing the I/O request. CLSDST always cancels any pending I/O requests for the 
disconnected terminal, and returns this return code in the I/O requests's RPL. 

12 (X'OC) 12 (X'OC) Request canceled by clear indicator 

While the request was being processed, you issued a SESSIONC macro instruction 
and sent a clear indicator to the terminal. This stops all data flow and cancels all 
pending I/O requests for the terminal. 

12 (X'OC) 13 (X'OD') Request canceled by a prior exception message 

A series of chained messages was being sent to the terminal and an exception 
response was returned for one of them. All subsequent SENDs for which 
POST=RESP applies for that chain are canceled with this return code. All SENDs in 
this chain for which POST=SCHED applies are accepted and posted for normal 
completion. 

16(X'10') Terminal or application program not available 

The terminal that you are attempting to acquire, or the application program to 
which you are attempting to pass a terminal, has been (or is in the process of being) 
deactivated by the network operator. 

If you are attempting to acquire a terminal, the terminal is unavailable, and your 
application program will have to proceed without it. If you are attempting to pass a 
terminal, the target application program is unavailable. Your action in the latter 
case depends on why you are attempting to pass the terminal to that application 
program. For example, if you are doing so in response to a terminal operator's 
request for reconnection, you will probably want to notify the terminal operator 
that the application program is unavailable. 

1 6 (X' 1 0') 1 OPNDST failed for logical unit 

The OPNDST failed because no network path could be obtained or because the 
logical unit does not exist. The SSENSEI and SSENSMI fields are set (these fields 
are described at the end of this appendix). 

16 (X'10') 2 Application program does not accept logon requests 

You attempted to disconnect a terminal and pass it to another application program, 
but logon requests cannot be queued for that application program. Logon-request 
queuing is not permitted because the application program issued SETLOGON with 
OPTCD=QUIESCE (indicating it no longer accepts logon requests) or it opened its 
ACB with MACRF=NLOGON (indicating it never accepts logon requests). 

1 6 (X' 1 0') 3 HALT (quick) issued 

The network operator has issued a HALT command, initiating a quick closedown. 
You cannot connect the terminal to your application program. 

A quick closedown means that you can no longer communicate with any terminals, 
and you should close the ACB. If you have a TPEND exit-routine, it was invoked. 

16(X'10') 4 VTAM/NCP incompatibility 

The I/O macro instruction failed because of incompatibilities between the output 
of the VTAM definition process and the Network Control Program generation 
process. 
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This problem can only be resolved by the installation. 

The incompatibility probably exists because of a modification and regeneration of 
the Network Control Program that was accomplished without a corresponding 
redefinition of VT AM. 

Before you can successfully attempt I/O with the terminal, the installation must 
remove the inconsistency that resulted in this return code. The most straight- 
forward way of accomplishing this is to redefine VTAM, using the same input that 
was used to generate the current Network Control Program. 

RTNCD FDBK2 

16 (X'10') 5 Permanent channel or link failure 

Either a permanent channel failure occurred in the channel that connects VTAM to 
the communications controller or to the control unit of a locally attached 3270 
Information Display System or a permanent link failure occurred on the link that 
connects VTAM to the remotely-attached communications controller. You can no 
longer communicate with this terminal. 

16 (X'10') 6 Automatic NCP shutdown 

The communications controller's Network Control Program has shut down for one 
of two reasons; either the network operator has manually initiated shutdown from 
the communication controller panel, or the Network Control Program did not 
receive a response from the operating system within the time limit specified during 
Network Control Program generation. You can no longer communicate with this 
terminal. 

16 (X'10') 7 Request canceled by VARY command 

The I/O operation has been canceled because the network operator deactivated the 
terminal while the macro instruction was being processed. If a LOSTERM 
exit-routine is available, it has been scheduled. You can no longer communicate 
with the terminal, and you should issue CLSDST to disconenct it from your 
application program. One reason the VARY command may have been issued is that 
the terminal may have been identified by a TOLTEP Test Request Message. 

16(X'10') 8 Dial-line disconnection 

A dial-line disconnection occurred after the macro instruction began execution, but 
before the I/O operation itself was initiated. If a LOSTERM exit-routine is 
available, it has been scheduled. If data is present in VTAM buffers, READ macro 
instructions can be issued to move the data into the application program. 

If the terminal is a dial-out terminal, reissuing the I/O macro instruction may cause 
contact to be reestablished. If the terminal is a dial-in terminal, or if contact cannot 
be established for a dial-out terminal, issue CLSDST for the terminal. 

16(X'10') 9 Unconditional Terminate Self received 

The logical unit has sent an unconditional Terminate Self command, which is a 
request for disconnection. No further communication with the terminal is possible. 
CLSDST must be issued. 

16 (X'10') 10 (X'OA') VTAM error 

An error occurred in VTAM itself. No further attempts to connect or disconnect 
the terminal should be made. 
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RTNCD FDBK2 

16 (X' 10') 1 1 (X'OB •) Dial-line disconnection (dial-out terminal) 

A dial-line disconnection occurred for a dial-out terminal while the I/O request was 
being processed. If reissuing this request does not cause contact to be reestablished, 
CLSDST should be issued for the terminal. 

Note that this return code applies to dial-in disconnections that occur while the I/O 
operation is in progress. When the dial-line disconnection occurs after the macro 
instruction begins execution but before the I/O operation is initiated— that is, while 
VTAM is waiting for a previous I/O operation to be completed— a RTNCD value of 
16 (decimal) and a FDBK2 value of 8 are returned. 

16(X'10') 12(X'0C) Dial-line dsconnection (dial-in terminal) 

A dial-line disconnection occurred for a dial-in terminal while the I/O request was 
being processed. CLSDST should be issued for the terminal. 

1 6 (X' 1 0') 13 (X'OD') VTAM inactive to your ACB 

The link between VTAM and your application program (ACB) that was established 
with OPEN has been broken. This may have occurred because you have elsewhere 
issued a CLOSE that has not yet completed, or it may have occurred because 
VTAM has become inactive. 

1 6 (X' 1 0') 14 (X'OE') Abend for program's TCB 

An abend condition occurred for the user's task control block (TCB). The request 
was not accepted, no ECB has been posted, and no RPL exit-routine has been 
scheduled. 

20 (X'14') VSAM request 

The RPL contains a VSAM or other non-VTAM request code. No ECB has been 
posted and no RPL exit-routine has been scheduled. 

20(X'14') 2 Zero EXIT field 

The RPL indicates that the ECB-EXIT field is being used as an EXIT field, but the 
RPL exit-routine address in it is 0. No RPL exit-routine has been scheduled. 

20(X'14') 3 Zero ECB field 

The RPL indicates that the ECB-EXIT field is being used to point to an external 
ECB, but the address in the field is 0. No ECB has been posted. 

20(X'14') 4 Inactive RPL checked 

CHECK was issued for an inactive RPL (an RPL that had been posted complete and 
for which CHECK has already been issued succesfully). All RPL-based macros must 
use an inactive RPL. All CHECK macros, however, must use an active RPL; an RPL 
cannot be checked twice. 

20 (X' 14') 16 (X' 10') Control block invalid 

The RPL's ACB field does not contain the address of a valid ACB. 

This may mean that the ACB field of the RPL was incorrectly set, the ACB has 
been destroyed, or it may mean that the ACB was opened by a task other than your 
own. This return code applies only in OS/VS2. 
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RTNCD FDBK2 

20(X'14') 17 (X'lT) RTYPE invalid 

A RECEIVE has been issued with the RTYPE field set to NDFSYN, NDFASY, and 
NRESP. 

20(X'14') 18(X'12') CLSDST in progress 

At the time this macro instruction was executed, a CLSDST request was pending 
for the terminal. The CLSDST request takes priority, and the request that caused 
this return code cannot be honored. 

20(X'14') 19(X'13') CID invalid 

Either the RPL's ARG field or the NIB's CID field does not contain a valid CID. 

You may have inadvertently modified the field or failed to set it in the first place, 
or you may have used the CID of a terminal that is no longer connected to your 
application program. 

Another possibility is that you violated the following rule: When placing a CID into 
the RPL's ARG field, always use the ARG key word- ARG=(6), for example— and 
when placing a NIB address into the RPL's NIB field, always use the NIB 
keyword— for example, NIB=(6). Since these two fields occupy the same four bytes 
in the RPL, VTAM can distinguish between a NIB address and a CID only through 
your use of the ARG or NIB keyword. Thus the presence of this return code could 
mean that you placed a NIB address in the RPL with the ARG keyword, and 
VTAM has rejected your "CID" as invalid. 

If this error code applies to CHANGE or CLSDST, you can reissue the macro 
instruction using the terminal's symbolic name rather than the CID. A new CID can 
be obtained by supplying the terminals's symbolic name to an INQUIRE 
(OPTCD=CIDXLATE) macro instruction. 

20(X'14') 20(X'14') CMD field invalid 
DO encountered an LDO whose CMD field does not contain a valid command code. 

Since invalid syntax (such as CMD=WRIET) specified instead of CMD=WRITE) 
would be revealed during program assembly, you either failed to set the CMD field 
before issuing DO, or you modified the CMD field incorrectly before VTAM 
processed the DO macro instruction. 

The RPL's AAREA field contains the address of the faulty LDO. If DO was 
processing a series of LDOs, no I/O for the previous LDOs has been initiated, even 
though those LDOs are valid. 

20 (X' 14') 21 (X' 15') WRTNRLG or WRTPRLG LDO not chained before 

READ 

You either failed to set the FLAGS field of a WRTNRLG or WRTPRLG LDO when 
you should have, or you used these LDOs with PROC=MSG, TRANS, or CONT 
instead of BLOCK. These LDOs must be command-chained to a READ LDO and 
PROC must be set to BLOCK. See the LDO macro instruction description for more 
information. 

20(X'14') 22(X'16') SOLICIT issued for an output-only terminal 

You issued SOLICIT (OPTCD=SPEC) for a terminal that the installation has 
defined as an output-only device. 
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20 (X'14') 23 (X'lV) READ issued for an output-only terminal 

You issued a READ (OPTCD=SPEC) for a terminal that the installation defined as 
an output-only device. 

20 (X'14') 23 (X'18') WRITE issued for an input-only terminal 

You issued a WRITE macro instruction for a terminal that the installation has 
defined as an input-only device. 

20 (X'14') 25 (X'19') WRITE (ERASE) issued for an invalid terminal 

You issued WRITE (OPTCD=ERASE) for the wrong type of terminal. Use this type 
of WRITE only to erase the screen of a display unit of a 3270 Information Display 
System, or of a 2265 Display Station attached to a 2270 Data Communications 
Terminal. 

20 (X' 14') 26 (X' 1 A') WRITE (EAU) issued for an invalid terminal 

You issued WRITE (OPTCD=EAU) for the wrong type of terminal. Use this type of 
WRITE only to erase the unprotected portion of the display unit screen of a 3270 
Information Display System. 

20 (X'14') 27 (X'lB') WRITE (CONV) issued for an output-only terminal 

You issued WRITE (OPTCD=CONV) for a terminal that the installation has defined 
as an output-only terminal. This is legitimate for an ordinary WRITE (OPTCD= 
NCONV), but a conversational WRITE includes an input operation. 

20 (X'14') 28 (X'lC) WRITE (ERASE and CONV) issued 

You issued a WRITE with both the CONV option code and either the ERASE or 
EAU option codes specified. You cannot erase a screen with a conversational 
WRITE macro instruction. 

20 (X' 14') 29 (X' ID') COPYLBM or COPYLBT LDO chained 

DO encountered a COPYLBM or COPYLBT LDO that had its FLAGS field set. 
You cannot set the FLAGS field of either of these LDOs (that is, you cannot 
command-chain them to other LDOs). 

The LDO has not been processed. The RPL's AAREA field contains the address of 
the faulty LDO. If DO was processing a series of LDOs, those preceding the faulty 
LDO have been successfully processed. 

20 (X'14') 30(X'1E') Invalid data or length 

You requested an input operation and either supplied an input work area address 
that is beyond the addressable range of your application program, or you invalidly 
indicated that the work area length is 0. 

Check the work area address and work area length fields in the RPL for an incorrect 
setting. For a DO macro instruction, these are the ADDR and LEN fields. For a 
READ macro instruction, these are the AREA and AREALEN fields. For a WRITE 
(OPTCD=CONV) macro instruction, these are the AAREA and AAREALN fields. 

20 (X'14') 31 (X'lF') LDO address invalid 

You issued a DO macro instruction, and indicated an LDO address that lies beyond 
the addressable range of the application program. Check the AREA field of DO's 
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RPL; you may have incorrectly modified the field, or never set an address in it 
before DO was executed. 

RTNCD FDBK2 

20(X'14') 35(X'23') Request type invalid 

When an I/O macro instruction is issued, VTAM sets the REQ field in the RPL to 
indicate the type of macro instruction that is using the RPL. The presence of this 
return code indicates that you modified that code before the requested operation 
completed. To avoid this and other related errors, never modify an RPL while it is 
in use. Compare with "VSAM request" (RTNCD=20, FDBK2=0). 

20(X'14') 36(X'24') Invalid FLAGS field for a READ LDO 

You misused the FLAGS field of a READ LDO. The FLAGS field cannot be used 
to command-chain a READ LDO to another LDO. See the description of the 
FLAGS operand in the LDO macro instruction for more information. 

The RPL's AAREA field contains the address of the faulty LDO. 

20(X'14') 37(X'25') WRITE (ERASE and BLK) issued 

You issued a WRITE (OPTCD=ERASE) macro instruction that also had the BLK 
option code specified. For a 3270 display screen, the use of BLK is never permitted 
in a WRITE macro instruction. For a 2770 display screen, the use of BLK together 
with ERASE is not permitted in the same WRITE macro instruction. 

20(X'14') 39(X'27') RESET option code invalid 

Before VTAM completed processing the RESET macro instruction, it discovered 
that the COND-UNCOND-LOCK option code was not properly set. Since you 
cannot incorrectly set this option code using VTAM macro instructions (the macro 
instruction would not be assembled), you have probably modified the RPL's 
OPTCD field with assembler instructions and destroyed the bit settings that 
represent COND, UNCOND, or LOCK. 

20(X'14') 40(X'28') WRITE (BLK) issued 

You used a WRITE macro instruction (or WRITE LDO) to send data to a display 
screen of a 3270 Information Display System, but the BLK option code is set. 
When writing to a 3270 display station, you can set the BLK-LBM-LBT option code 
to either LBM or LBT, but not to BLK. 

20 (X' 14') 41 (X'29') READBUF used with invalid terminal 

You used a READBUF LDO for an ineligible device. Use the READBUF LDO only 
for a display station of a 3270 Information Display System. 

20 (X' 14') 42 (X'2A') COPYLBM or COPYLBT used with invalid terminal 

A COPYLBM or COPYLBT LDO can only be used with a 3277 display station as 
the "from" device. 

20 (X' 14') 43 (X'2B') WRITE (CONV) when data expected 

A WRITE (OPTCD=CONV) was issued to a terminal from which data is already 
expected because of a previous READ, SOLICIT, or conversational WRITE 
operation. 
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20(X'14') 44(X'2C) Output not preceded by input 

You used a RESET or WRITE macro instruction, or a WRITE LDO, for a 3735 
Programmable Buffered Terminal without first using a SOLICIT or READ 
(OPTCD=SPEC) macro instruction, or a READ LDO. 

The first I/O request directed at this type of terminal following connection must be 
a request that causes data to be solicited from the terminal. 

20 (X' 14') 45 (X'2D') RESET (COND) issued-error lock set 

You issued a RESET (OPTCD=COND) macro instruction for a terminal, but an 
error lock is set for that terminal. This form of RESET cannot be used if the error 
lock is set. The UNCOND form of RESET is valid in this situation, however, and 
the LOCK form may be valid as well. See the RESET macro instruction description. 

20 (X'14') 46 (X'2E') BLOCK-MSG-TRANS-CONT invalid 

While processing a solicit request, VTAM discovered that the BLOCK-MSG- 
TRANS-CONT processing option was not properly set in the NIB when OPNDST 
was issued. You may have inadvertently modified this field, or used a processing 
option not valid for the device. See the NIB macro instruction for further 
information. 

20 (X' 14') 47 (X'2F') Too many leading graphic characters 

You attempted to send too many leading graphic characters with a positive or 
negative response. 

When you use the WRTPRLG or WRTNRLG LDOs, the ADDR and LEN fields of 
the LDO must indicate the address and number of leading graphic characters to be 
sent. The maximum number that can be sent is 15; the value you placed in the LEN 
field exceeds this limit. 

The RPL's AAREA field contains the address of the invalid LDO. 

20 (X' 14') 48 (X'30') Invalid LEN (COPYLBM or COPYLBT LDOs) 

You failed to properly set the LEN field of a COPYLBM or COPYLBT LDO. 

When you use either of these LDOs, the ADDR field must indicate the address of a 
3-byte data area. Even though the length of this area is fixed, the LEN field must 
nevertheless be set to 3. VTAM found a value in the LEN field that was not 3. 

20(X'14') 49(X'31') Invalid data area 

Either all or part of the output data area lies beyond the addressable range of your 
application program. 

20 (X' 14') 50 (X'32') Request invalid for specified device 

The I/O request failed because the requested operation is invalid for the particular 
type of terminal to which it is directed. The error lock has been set. 

This return code results when you violate these rules: 

When you establish NIB processing options with OPNDST or CHANGE, do not 
use a processing option that is not applicable for the particular device that is the 
object of the OPNDST or CHANGE macro instruction. Figure 6 (at the end of 
the NIB macro instruction description) shows which processing options apply to 
each type of terminal. 



Appendix C: Return Codes for RPL-Based Macros 195 



Use the READ, WRITE, WRITELBM, WRITELBT, WRTHDR, WRTPRLG, and 
WRTNRLG LDOs only with a System/3 or System/370 CPU. 

RTNCD FDBK2 

20 (X' 14') 5 1 (X'33') WRITE canceled (input data arriving) 

You attempted to send data to a terminal at the same time that data was being 
solicited from it. Normally, this is no problem because the write operation is 
suspended until the solicitation is completed. For a BSC device, however, the write 
operation is canceled unless the terminal has just sent a data block ending with an 
ETX character (that is, has just finished sending a message). 

Thus for a BSC device, the receipt of this return code indicates that when the 
WRITE was issued, the terminal was sending data that was not the last block of a 
message, and the write operation has been canceled. 

20 (X' 14') 52 (X'34') First I/O request not READ or SOLICIT 

For a dial-in BSC terminal, the first I/O request following connection must be a 
SOLICIT or READ (OPTCD=SPEC) macro instruction. You have used some other 
macro instruction as your first I/O request. 

20 (X'14') 53 (X'35') Terminals not attached via same control unit 

You attempted to use the COPYLBM or COPYLBT LDO to move data between 
two 3270 terminals that are not part of the same 3270 Information Display 
System. The terminals that are the objects of these LDOs must be connected to the 
same control unit. 

You have incorrectly specified the identities of the two terminals. The ARG field of 
the DO macro instruction's RPL must contain the CID of the "to" terminal. The 
ADDR field of the LDO must contain the address of a 3 -byte data area; the first 
byte of this data area must contain a 3270 copy control character, and the 
remainder of the data area must consist of the right-most two bytes of the "from" 
terminal's CID. 

The error lock is set for the receiving terminal (the terminal whose CID is in the 
ARG field),but not for the "from" terminal. 

20(X'14') 54(X'36') RESET (LOCK) invalid 

You attempted to use the LOCK form of RESET in a situation in which you should 
have used the UNCOND form of RESET instead. 

For an explanation of the restrictions that apply to the LOCK form of RESET, see 
the description of the RESET macro instruction (OPTCD=LOCK). 

20(X'14') 55(X'37') Terminal not connected 

You attempted to use the COPYLBM or COPYLBT LDO but the "from" terminal 
is not connected to your application program. More precisely, the "from" terminal 
is not connected via the ACB that you indicated in the RPL's ACB field. 

20(X'14') 57(X'39') Invalid PROC option 

VTAM completed an OPNDST normally but the setting you supplied in the NIB's 
field is invalid. This error is detected when the first I/O request is issued for the 
terminal. 
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20 (X'14') 59 (X'3B') NFME-NRRN response 

You attempted to send an exception response with the RESPOND field set to 
NFME and NRRN. A response must be identified as FME, RRN, or both; in effect, 
you have identified the response as neither. 

20 (X'14') 60 (X'3C) Previous scheduled output still pending 

You issued a SEND (POST=SCHED) or SESSIONC macro instruction before a 
previous one had been completed. Only one such macro instruction can be 
outstanding at one time. After the previous macro instruction has been completed, 
this macro instruction can be reissued. 

20 (X'14') 64(X'40') CONTROL invalid 

You modified the bits in the CONTROL field, or you used a CONTROL value for a 
SESSIONC macro instruction that was not SDT, CLEAR, or STSN. 

20 (X' 14') 65 (X'41') No SDT issued 

You attempted to communicate with a terminal to which no start-data-traffic 
(SDT) indicator has been sent. Until a terminal is sent an SDT indicator, no traffic 
flow is possible; only SDT, set-and-test-sequence-numbers (STSN), ready-to-receive 
(RTR), and clear indicators can be exchanged. Every time a clear indicator is sent 
to the terminal, a new SDT indicator is required before traffic flow can resume. 

20 (X'14') 68(X'44') RESPLIM exceeded 

The number of outstanding SEND (POST=RESP) macro instructions for a terminal 
exceeds the RESPLIM value set in the terminal's NIB. 

20 (X'14') 68(X'47') 3270 SEND option invalid 

The RPL pointed to by your SEND macro was for a 3270 in record-mode and had 
one or more of the following invalid settings in effect: STYPE=RESP, RESPOND= 
NFME, CHAIN set to other than ONLY, or CONTROL set to other than DATA. 

20 (X'14') 72(X'48') Redundant clear indicator 

You attempted to send a clear indicator to the terminal but no start-data-traffic 
indicator has been sent. Since traffic flow is already stopped, the clear indicator is 
redundant. 

20 (X'14') 73(X'49') Invalid STSN indicator 

You attempted to send a set-and-test-sequence-number (STSN) indicator to the 
terminal and set the IBSQAC and/or OBSQAC fields to some value other than SET, 
TESTSET, IGNORE, or INVALID. See Figure 12 in the SESSIONC macro 
instruction description. 

20 (X'14') 74 (X'4A') Application program name not available 

You issued an INTRPRET macro instruction; VTAM has located the appropriate 
entry in the interpret table, and found that the installation has specified a routine 
to provide the identity. That routine, however, has not been loaded. 

20 (X'14') 75 (X'4B') INTRPRET sequence invalid 

You issued an INTRPRET macro instruction but VTAM cannot locate an entry in 
the interpret table that corresponds to the sequence you provided. 
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You may have inadvertently modified the sequence or the address in the RPL's 
AREA field which points to the sequence. Or, the installation may have failed to 
properly define the entry in the interpret table. 

Once your application program has been tested and debugged, and you know that 
none of the foregoing situations exists, you can assume this: the terminal operator 
or program that initiated the logon request must have passed your application 
program an invalid logon sequence. 

RTNCD FDBK2 

20(X'14') 76(X'4C) No terminal or application program name 

You issued INQUIRE or INTERPRET, and failed to properly provide VTAM with 
the identity of the terminal or application program: 

• INQUIRE (OPTCD=APPSTAT) was issued and the name was not that of an 
application program. 

• INQUIRE (OPTCD=BSCID) was issued and the name was not that of a terminal 
containing a UTERM parameter in its TERMINAL entry. 

• INQUIRE (OPTCD=TERMS) was issued and the name was not that of a cluster, 
component, terminal, line, group, local 3270, logical unit, or UTERM entry. 

• INQUIRE (OPTCD=DEVCHAR) was issued and the name is that of an 
application program. 

• INQUIRE (OPTCD=LOGONMSG) was issued and no logon requests were 
queued for the application program. 

• INQUIRE (OPTCD=LOGONMSG) was issued and the name was not that of a 
terminal, component, local 3270, or logical unit. 

• INTRPRET was issued and the name was not that of a terminal, component, or 
logical unit. 

Assuming that the installation properly defined the entry in the resource definition 
table for the terminal or application program, you have probably done one of the 
following: (1) failed to place a valid CID in the RPL's ARG field; (2) failed to place 
a valid NIB address in the RPL's NIB field, or (3) if you did set the RPL's NIB field 
correctly, you failed to set a valid symbolic name in the NIB's NAME field. 

20 (X' 14') 77 (X'4D') No interpret table 

You issued an INTRPRET macro instruction, but there is no interpret table for the 
terminal. The installation may have failed to include an interpret table for this 
terminal during the VTAM definition process. 

20 (X' 14') 78 (X'4E') Invalid use of a NIB list 

You attempted to accept a terminal without setting the NIB's LISTEND field to 
YES. 

When OPNDST (OPTCD= ACCEPT) is issued,, the NIB pointed to by the RPLmust 
have its LISTEND field set to YES. Since this is the LISTEND setting that is 
assumed unless you specify otherwise, you must have used the LISTEND=NO 
operand when you last modified the NIB. 

20 (X' 14') 79 (X'4F') ACQUIRE-ACCEPT option code invalid 

The OPNDST request failed because bits in the OPTCD field have been incorrectly 
set. The particular bits that have been incorrectly set are those that form the 
ACQUIRE-ACCEPT option code. This return code does not mean that the 
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ACQUIRE option was erroneously used in place of ACCEPT, or vice versa; it means 
that neither ACCEPT nor ACQUIRE is indicated in the OPTCD field. 

Since you cannot cause the field to be incorrectly set in this manner by using 
VTAM macro instructions, you inadvertently modified the OPTCD field with 
assembler instructions. 

RTNCD FDBK2 

20 (X' 14') 80 (X'50') CONANY-CONALL option code invalid 

The OPNDST failed because the bits in the RPL's OPTCD field have been 
incorrectly set. The particular bits that have been incorrectly set are those that 
form the CONANY-CONALL option code. This return code does not mean that the 
CONANY option was erroneously used in place of CONALL, or vice versa; it means 
that neither CONALL nor CONANY is indicated in the OPTCD field. 

Since you cannot cause the field to be incorrectly set in this manner by using 
VTAM macro instructions, you may have inadvertently modified the OPTCD field 
with assembler instructions. 

20(X'14') 81 (X'51') Application program never accepts 

You attempted to accept a terminal or generate a simulated logon request for a 
terminal, but logon request queuing cannot occur because you opened your ACB 
with MACRF=NLOGON. 

20(X'14') 82(X'52') NIB invalid 

The request failed because there is no NIB at the location indicated in the RPL's 
NIB field. 

20 (X'14') 83 (X'53') Terminal or application program not found 

The symbolic name you supplied in the NIB's NAME field or indicated via the 
RPL's AAREA field does not have a corresponding entry in the resource definition 
table. Either you failed to correctly set the NAME field, or the installation did not 
include the entry in the resource definition table during VTAM definition. 

20(X'14') 84(X'54') Invalid terminal name 

The symbolic name you supplied in the NIB's NAME field corresponds to an entry 
in the resource definition table, but the entry is for a node with which you cannot 
establish connection— such as another application program, or the Network Control 
Program of a communications controller. The only entries you can identify in the 
NAME field for OPNDST are the names of LU, TERMINAL, COMP, or LOCAL 
entries. 

20(X'14') 85(X'55') OPNDST (ACQUIRE) not authorized 

You attempted to acquire a terminal (SIMLOGON or OPNDST) but the installation 
has denied you authorization to do so. 

The installation may have specified during VTAM definition that your application 
program is not authorized to acquire any terminals. If you are authorized to acquire 
terminals and you still receive this return code, this means that an installation 
authorization routine has been invoked, and has determined that you cannot 
acquire the specific terminal indicated in your request. 
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RTNCD FDBK2 

20(X'14') 86(X'56') Invalid MODE field 

You either specified MODE=BASIC for a logical unit or record-mode 3270, or you 
specified MODE=RECORD for a BSC, start-stop, or basic-mode 3270 terminal. 

20(X'14') 87(X'57') No MODE field 

You issued an OPNDST or CHANGE macro instruction, and failed to set the NIB's 
MODE field to BASIC or RECORD. 

20 (X'14') 91 (X'5B') Invalid logon message address 

The address of the logon message that you supplied in the RPL's AREA field lies 
beyond the addressable range of your application program. 

20(X'14') 92(X'5C) Duplicate terminal names 

You supplied a NIB list and attempted to acquire the group of terminals 
represented in that list. VTAM found that at least two of the NIBs contain the same 
symbolic name in their NAME fields. None of the terminals have been connected to 
your application program. 

20 (X' 14') 93 (X'5D') OPNDST invalid (terminal not connected) 

The terminal represented by the CID you supplied is not connected to your 
application program. 

This return code applies to CHANGE or CLSDST (either OPTCD=PASS or 
OPTCD=RELEASE) used with a terminal's CID. 

You may have placed the wrong CID into the ARG field, or neglected to place a 
CID there at all (perhaps the field still contains a CID left over from a previous 
CLSDST request). 

20(X'14') 94(X'5E) CLSDST (PASS) not authorized 

CLSDST (OPTCD=PASS) is a function whose use is authorized by the installation. 
You attempted to use this function, but the installation has not authorized you to 
pass terminals to other application programs. This CLSDST macro instruction 
should have been issued with RELEASE in affect, not PASS. 

20(X'14') 95(X'5F') CLSDST (PASS) invalid 

You attempted to disconnect a terminal that is not connected to your application 
program. This return code applies to CLSDST (OPTCD=PASS) used with a 
terminal's symbolic name. 

(CLSDST with a terminal's symbolic name is implemented by (1) placing the 
address of a NIB in the NIB field of CLSDST's RPL and (2) placing the terminal's 
symbolic name in the NAME field of that NIB.) 

20(X'14') 96(X'60') CLSDST (RELEASE) invalid 

You attempted to disconnect a terminal that is not connected to your application 
program, or had no logon request queued for your application program. This return 
code applies to CLSDST (OPTCD=RELEASE) used with a terminal's symbolic 
name. 

The explanation provided for the previous return code (RTNCD value of 20 and 
FDBK2 value of 95) also applies to this return code. 
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RTNCD FDBK2 

20(X'14') 97(X'61') Invalid SETLOGON 

You issued SETLOGON but the ACB's logon request queue cannot be opened. 

Either you opened the ACB with its MACRF field set to NLOGON or you already 
issued SETLOGON (OPTCD=QUIESCE) and permanently closed the logon request 
queue. All forms of SETLOGON are thus invalid, since you are either attempting to 
open a logon request queue that cannot be opened, or you are attempting to close a 
logon request that is already closed. 

20(X'14') 98(X'62') Wrong mode 

You either attempted to issue a basic-mode macro for a terminal that was 
connected with MODE=RECORD, or you attempted to use a record-mode macro 
for a terminal that was connected with MODE=BASIC. See the MODE operand of 
the NIB macro instruction. 

The FDBK Field The FDBK field is set when a READ, WRITE, DO, or INQUIRE (OPTCD= 

APPSTAT) macro instruction is completed successfully. 

For READ, WRITE, and DO, any combination of the bits shown below may be set 
in the FDBK field. Although you can test the FDBK field by coding FDBK=value 
on a TESTCB macro instruction, a simpler method is available: You can code 
DATAFLG=UNSOL, EOB, EOM, EOT, LG, or SOH on a TESTCB macro 
instruction. For example: 

TESTCB RPL=RPLl,DATAFLG=SOH 

An equal PSW condition code indicates that the corresponding bit is set on. The 
following table indicates the appropriate operand for each bit. 

You may wish to use SHOWCB to examine the FDBK field. As is true with the 
RTNCD and FDBK2 fields, SHOWCB places the FDBK field in the right-most byte 
of your fullword area, and sets the high-order three bytes to zero. Thus for 
purposes of SHOWCB, the bit positions shown below (0, 1,2 ... 7) become bit 
positions 24, 25, 26 ... 31. 

For the INQUIRE macro instruction (OPTCD= APPSTAT), one of the values shown 
below is returned in the FDBK field. You can use either TESTCB or SHOWCB to 
determine the contents of FDBK. Note that although combinations of bits are set 
for READ, WRITE, and DO, a single numerical value is set in FDBK for INQUIRE. 

FDBK codes for READ, WRITE, and DO are as follows: 
Bit Position TESTCB Operand Explanation 

0: x DATAFLG=UNSOL Unsolicited input. For READ (or DO, 

with CMD=READ), this indicates that the 
data was not solicited from the terminal 
by your application program. For WRITE 
(or DO, with CMD=WRITE LDO), this 
indicates that data was received instead of 
an acknowledgment, or that leading 
graphic characters were received with the 
acknowledgment. 

1 : .x None Reserved. 
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DATAFLG=EOB 



DATAFLG=EOM 



DATAFLG=EOT 



x . . None 

. x . DATAFLG=LG 



7: x DATAFLG=SOH 



End of block. For a READ or conversa- 
tional WRITE, this indicates that the 
input data block ended with an EOB. 
This bit is not set if overlength data is 
present (which is possible if the KEEP 
option code is in effect). This bit is set 
for the READ that obtains the last 
portion of the overlength data, however. 
If this bit is set on, you will probably 
want to next determine if the EOM 
indicator is set. 

End of message. For a READ or conversa- 
tional WRITE, this indicates that the 
input data block ended with an ETX. 
This bit setting applies only to BSC 
devices. If this bit is set on, you will 
probably want to next determine if the 
EOT indicator is set. 

End of transmission. For a READ or 
conversational WRITE, this indicates that 
the last block of a transmission was 
received. The RPL's RECLEN field must 
be checked; if it is set to 0, the EOT 
arrived unaccompanied by data. If 
RECLEN contains a non-zero value, a 
block of data (of the length indicated by 
RECLEN) accompanied by an EOT was 
received. 

Reserved. 

Leading graphic characters received. This 
bit is set only for READ, and indicates 
that leading graphic characters have been 
received (without data). This code is only 
set on for binary synchronous terminals. 

Heading block received. For a READ, 
this indicates that a heading block was 
received and placed in your input area. If 
RTNCD is set to the data block 
associated with the heading block can be 
obtained with another READ macro 
instruction. If RTNCD is set to 12 
(decimal), there is no associated data 
block— that is, the heading block arrived 
unacompanied by data. This code is only 
set on for binary synchronous terminals. 



FDBK codes for INQUIRE are as follows: 
FDBK Value Explanation 

Application Program active: 



The application program is accepting logon requests. 

Application program inactive: 

The application program has not yet opened its ACB. 
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FDBK Value Explanation 

8 Application program never accepts: 

The application program never accepts logon requests. That is, 
the application program opened its ACB with 
MACRF=NLOGON specified. 

C Application program temporarily not accepting: 

The application program normally accepts logon requests, but 
it has indicated that logon requests are not to be directed at it 
for the time being. That is, the application program opened its 
ACB with MACRF=LOGON specified, but has subsequently 
issued SETLOGON (OPTCD=STOP). Since the use of this type 
of SETLOGON implies a temporary closing of the logon 
request queue, you can periodically reissue INQUIRE to 
determine when the application program reopens its logon 
request queue. You will know that logon requests can again be 
directed at the application program when INQUIRE returns a 
value of in FDBK. 

10 Application program no longer accepting: 

The application program normally accepts logon requests, but 
it has permanently closed its logon request queue. That is, it 
has issued SETLOGON (OPTCD=QUIESCE). No more logon 
requests can be directed at the application program. Presum- 
ably, it is about to close its ACB. 



The SENSE Field 
(Basic-mode only) 



The SENSE field is set following READ, WRITE, and DO macro instructions when 
the device returns error status information. 



The Logical Unit Sense Fields 



The SENSE field consists of the response and extended response bytes that are 
forwarded by the NCP for the following terminals: 

2770 Data Communication System 

2780 Data Transmission Terminal 

3270 Information Display System (basic-mode) 

3740 Data Entry System 

3780 Data Transmission Terminal 

The field can be tested directly with the TESTCB macro instruction, or the field 
can be extracted with the SHOWCB macro instruction or examined with assembler 
instructions. SHOWCB requires that you provide a fullword work area in your 
application program for the SENSE field. The SENSE field contains two 
meaningful bytes of information; for SHOWCB, this information is right-justified in 
the fullword work area, and the unused portion is set to 0. The specific bits that are 
set in the SENSE field are identified and explained in the component description 
manual for the particular terminal or system. 

When the application program or a logical unit receives an exception response or a 
logical-unit-status (LUS) indicator, the response or indicator includes information 
regarding the reason for the exception condition. There are three types of 
information that describe the exception condition: 

• System sense information 

• System sense modifier information 

• User sense information 
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System sense information indicates one of five major classes of system-defined 
error. 

System sense modifier information indicates one of many specific causes of the 
error indicated by the system sense information. Like RTNCD and FDBK2, the 
system sense and system sense modifier information together form a specific type 
of error condition within a general class of error conditions. These error conditions 
are described below. 

User sense information is used when the error condition is detected by the 
customer-written program itself. No particular codes or values are defined by IBM 
to indicates types of errors. The node must generate its own user sense information 
that will be understood by the other node. 

These three types of sense information— system, system modifier, and user— are set 

in RPL fields. Three fields (one for each type of sense information) are set by the 

application program when it sends an exception response or LUS indicator to the 

logical unit. Three other fields are set by VTAM when the application program 

receives an exception response or LUS indicator from the logical unit. These are the 

names of the six fields, as they would be used on a manipulative or RPL macro 

instruction: ^ , 

Output from 

Input to the the Application 

Application Program Program 

System sense information SSESNSEI SSENSEO > 

System sense modifier information SSENSMI SSENSMO 

User sense information USENSEI USENSEO 

The values that are set in the system sense and system sense modifier fields are 
fixed pre-defined codes established by IBM. The values for the system sense field 
are as follows (the operands shown here are those used on a MODCB or TESTCB 
macro instruction): 

SSENSEI=PATH An unrecoverable PATH error occurred. The message could 

not be delivered to the intended receiver due to a physical 
problem in the network path. No recovery action is 
possible. Disconnect the terminal. 

SSENSEI=CPM An unrecoverable error occurred. Disconnect the terminal. 

SSENSEO=CPM 

SSENSEI=STATE An error occurred in the node's use of sequence numbers, 
SSENSEO=STATE chaining indicators, bracket indicators, or change-direction 

indicators. This error is recoverable; use clear, STSN, and 

SDT indicators. 

SSENSEI=FI A Function Interpreter error occurred; the node cannot 

SSENSEO=FI handle the message because the message itself is invalid. 

This error may or may not be recoverable. 

SSENSEI=RR A Request Reject error occurred; the node cannot handle 

SSENSEO=RR the message because of some external condition (the 

message itself is invalid). This error is recoverable. 

The following values in the system sense modifier field define the specific type of 
error (the operands shown here are those used on a MODCB or TESTCB macro 
instruction): 
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When the system 
sense field is set to: 

SSENSEI=PATH 

SSENSEI=CPM 
SSENSEO=CPM 

SSENSEI=STATE 
SSENSEO=STATE 



SSENSEI=FI 
SSENSEO=FI 



SSENSEI=RR 
SSENSEO=RR 



The system sense 
modifier field 
can be set to 

Unpredictable 
Unpredictable 

SSENSMI=1 
SSENSMOl 



SSENSMI=2 
SSENSM02 

SSENSMI=3 
SSENSM03 

SSENSMI=4 
SSENSM04 

SSENSMI=6 
SSENSM0=6 



Meaning 



SSENSMI=2 
SSENSM0=2 

SSENSMI=3 
SSENSM0=3 

SSENSMI=5 
SSENSM0=5 



SSENSMI=7 
SSENSM0=7 

SSENSMI=8 
SSENSM0=8 

SSENSMI=2 
SSENSM0=2 



A sequence number error occur- 
red (the number received for a 
DFSYN message was not 1 great- 
er than the previous DFSYN 
message). 

A chaining error occurred. 



A bracket error occurred (such 
as an attempt to end a bracket 
before one has been started). 

A change-direction error occur- 
red. 

A DFSYN message was received 
from a logical unit that has 
previously sent a quiesce- 
completed indicator and has not 
yet responded to a release- 
quiesce indicator. 

Length error; the message is too 
long or too short. 

The indicator in the message is 
not used by the node. 

The indicator in the message is 
used by the node, but a parame- 
ter modifying that indicator is 
invalid. 

The category of indicator in the 
message is not used by the node. 

The Function Management 
Header is not understood or is 
not translatable by the node. 

Operator intervention is required 
(for example, the device may be 
temporarily in local mode, or 
forms or cards may be required.) 



SSENSMI=10 The receiver has denied an 

SSENSMO=10 implicit or explicit request of 

the sender. 

SSENSMI=17 The current chain should be 

SSENSMOl 7 terminated with CHAIN=LAST 

or with a cancel indicator. 
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SSENSEI=RR 
SSENSEO=RR 



SSENSMI=19 
SSENSM0=19 



SSENSMI=20 
SSENSMO20 



SSENSMI=25 
SSENSMO=25 

SSENSMI=27 
SSENSMO=27 

SSESNMI=28 
SSENSMO=28 



Both nodes attempted to begin a 
bracket at the same time. The 
message to which this response 
applies did not begin the brack- 
et. 

Both nodes attempted to begin a 
bracket at the same time. The 
message to which this response 
applies began the bracket. 

The receiver of a ready-to- 
receive (RTR) indicator has 
nothing to send. 

The receiver of a message is not 
handling input and so has reject- 
ed the message. 

The indicator in the message is 
normally used by the node, but 
some external condition is tem- 
porarily preventing its use. 
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APPENDIX D. RETURN CODES FOR MANIPULATIVE MACRO INSTRUCTIONS 



When the application program receives control from any of the manipulative macro 
instructions (GENCB, MODCB, TESTCB, or SHOWCB), register 15 is set to one of 
the values shown below. 

The macro instruction was completed successfully. 

If the macro instruction is GENCB, and the control block (or blocks) have 
been built in dynamically allocated storage, register 1 contains the address 
of the control blocks and register contains their total length (in bytes). 

4 An error occurred. A return code is placed in register indicating the 

cause of the error (see Figure D-l). 

8 An error occurred. Specifically, an attempt has been made to use the 

execute form of the macro instruction to enter a new item in the 
parameter list. (Only modifications to existing parameters lists are allowed, 
as explained in Appendix F.) Register is not set. 

12 A DOS/VS system control error occurred. These errors involve the READ 

and SIZE operands of the EXEC statement used to initiate the application 
program (the EXEC statement is described in DOS/VS System Control 
Statements, GC33-5376. A return code indicating the cause of the error is 
placed in register (see Figure D-2). 

When a return code of 4 or 12 is placed in register 15, an error return code is placed 
in register 0. Figures D-l and D-2 explain these error return codes, and indicates 
which manipulative macro instructions are capable of returning each code. 



Value Applicable Macro Instructions 

GENCB MODCB SHOWCB 

1 X X X 



X 



X 



X 



X 



X 



X 



X 



X 



TESTCB 
X 



X 



X 



X 



X 



Explanation 



Invalid request type: You modified the list form's 
parameter list. When the access method processed the 
execute form, it found that the part of the parameter 
list that indicates the type of request (MODCB, 
SHOWCB, TESTCB, or GENCB) had been destroyed. 

Invalid block type: You modified the list form's 
parameter list. When the access method processed the 
execute form, it found that the part of the parameter 
list which indicates the type of control block (ACB, 
EXLST, RPL, or NIB) had been destroyed. 

Invalid keyword: You modified the list form's 
parameter list. When the access method processed the 
execute form, it found that part of the parameter list 
representing keyword types (FIELDS=, ERET=, etc.) 
had been destroyed. 

Invalid block: The address specified with the ACB, 
EXLST, RPL, or NIB keyword did not indicate a 
valid ACB, EXLST, RPL, or NIB control block, 
respectively. 

Reserved (VSAM only) 



Figure D-l (Part 1 of 2). Register Return Codes for Manipulative Macros When Register 15 is Set to 4 
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Value 

6 

7 



Applicable Macro Instructions 
GENCB MODCB SHOWCB TESTCB 



X 



X 
X 



X 



X 



Explanation 



Reserved (VSAM only) 

Field nonexistent: You attempted to modify or 
extract a field from an exit list, but ihe specified field 
does not exist. For example, you may have specified 
MODCB EXLST=EXLST1,LERAD=LERADPGM in 
order to place a valid address (LERADPGM) in 
EXLSTl's LERAD field. The receipt of this return 
code means that EXLST1 has no LERAD field; you 
never specified one on an EXLST or GENCB macro 
instruction. 

Insufficient main storage: There is not enough main 
storage in which to build the control block or blocks. 



10 

11 
12 

13 
14 



X 



X 
X 

X 
X 



15 
16 

17 



X 
X 



X 



X 
X 



X 



X 



Insufficient program storage: The work area length 
you indicated with the LENGTH operand was not 
large enough to build the control blocks (GENCB) or 
to hold the control block fields (SHOWCB). 

No address supplied (GENCB,MODCB): You 
attempted to generate an EXLST entry without 
specifying an address. For example, coding TPEND= 
is invalid. 

RPL active: You attempted to modify an RPL that 
was active (it must be inactive). 

ACB open: You attempted to modify an ACB after it 
had been opened (the ACB must not be opened when 
you modify it). 

Reserved (VSAM only). 

Invalid parameter list: You modified the list form's 
parameter list. When the access method processed the 
execute form, it found that the parameter list now 
indicates mutually exclusive keywords (as though you 
had, for example, specified 
BLK=RPL,ECB=ECB1,EXIT=PGM on a GENCB 
macro instruction). 

Invalid alignment: The work area in your application 
program does not begin on a fullword boundary. 

Invalid access method: You coded AM=VTAM on the 
macro instruction and included one or more 
parameters that are valid only for VSAM. 

No internal ECB: TESTCB (IO=COMPLETE) failed 
because there is no internal ECB in the RPL. 



Figure D-l (Part 2 of 2). Register Return Codes for Manipulative Macros When Register 15 is Set to 4 
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Value Applicable Macro Instructions Explanation 

GENCB MODCB SHOWCB TESTCB 

4 X X X X DOS/ VS system control error: The SIZE operand was 

omitted from the application program's EXEC 
statement. 

8 X X X X DOS/VS system control error: An attempt was made 

to run in real mode. 

12 X X X X DOS/VS system control error: The value of the SIZE 

operand does not allow enough space for VTAM 
modules. 

Figure D-2. Register Return Codes for Manipulative Macros When Register 15 is Set to 12 (DOS/VS only) 
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APPENDIX E. SUMMARY OF OPERAND SPECIFICATIONS FOR THE 
MANIPULATIVE MACRO INSTRUCTIONS 



The first figure in the appendix (Figure E-l) deals with all of the operands of the 
manipulative macro instructions (GENCB, MODCB, SHOWCB, and TESTCB) that 
do not involve a particular control block field. The remaining figures deal 
exclusively with the operands you use to select the control block field or fields to 
be set, moved, or tested. These figures indicate which manipulative macro 
instructions apply for each operand and the types of values that can be coded with 
each operand. 

For example, suppose you are interested in examining an ACB's OFLAGS field. 
Turning to Figure E-2, you locate the OFLAGS entry and note that TESTCB (but 
not SHOWCB) can be used to examine this field. Checking the OFLAGS entry 
further, you will note that this operand is coded in a fixed form— in this case, 
OFLAGSOPEN. 

The "Notation Category" and "Example" columns in Figures E-2 through E-5 do 
not apply to the SHOWCB macro instruction, where the control block field name is 
always coded after the FIELDS keyword (for example, FIELDS=PASSWD). 

There are many different ways that a given operand might be coded, but the 
number of valid combinations is small. The valid coding combinations for each 
operand have been grouped under the heading "Notation Category" in Figures E-l 
through E-5. Three of these categories, called the address, quantity, and fixed value 
categories, encompass almost all of the operands. A few operands fall into 
categories identified as the name, register-indirect value and indirect value 
categories. 



Operand 
Keyword 


GENCB 


Vali 
MODCB 


dfor 
SHOWCB 


TESTCB 


Notation Category 


Example 


ACB 




X 


X 


X 


Address 


ACB=ACB1 


AM 


X 


X 


X 


X 


Fixed Value 


AM=VTAM 


AREA 






X 




Address 


AREA=WORKAREA 


BLK 


X 








Fixed Value 


BLK=RPL 


COPIES 


X 








Quantity 


COPIES=7 


ERET 








X 


Address 


ERET=ERRPGM 


EXLST 




X 


X 


X 


Address 


EXLST=EXLST1 


FIELDS 






X 




Fixed Value 


FIELDS=(ARG,ECB) 


LENGTH 


X 




X 




Quantity 


LENGTH=132 


MF 


X 


X 


X 


X 


See Appendix F 


MF=(E,PARMLIST) 


NIB 




X 


X 


X 


Address 


NIB=NIB1 


RPL 




X 


X 


X 


Address 


RPL=RPL1 


WAREA 


X 








Address 


WAREA=WORKAREA 



Figure E-l. Manipulative Macro Instruction Operands Exclusive of Control Block Field Operands 
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Operand 
Keyword 


GENCB 


Valic 
MODCB 


Ifor 
SHOWCB 


TESTCB 


Notation Category 


Example 


ACBLEN 






X 


X 


Quantity 


ACBLEN=(7) 


AM 


X 








Fixed Value 


AM=VTAM 


APPLID 


X 


X 


X 


X 


Address 


APPLID=AREA 


ERROR 






X 


X 


Quantity 


ERROR-13 


EXLST 


X 


X 


X 


X 


Address 


EXLST=EXLST2 


MACRF 


X 


X 




X 


Fixed Value 


MACRF= LOGON 


OF LAGS 








X 


Fixed Value 


OFLAGSOPEN 


PASSWD 


X 


X 


X 


X 


Address 


PASSWD=PASSWD1 



Figure E-2. Manipulative Macro Instruction Operands for ACB Fields 



Operand 
Keyword 


GENCB 


Valid f 
MODCB 


or 
SHOWCB 


TESTCB 


Notation Category 


Example 


DFASY 


X 


X 


X 


X 


Address 


DFASY=(3) 


RESP 


X 


X 


X 


X 


Address 


RESP=RESPEXIT 


SCIP 


X 


X 


X 


X 


Address 


SCIP=(*,SCIPADR) 


ATTN 


X 


X 


X 


X 


Address 


ATTN=ATTNRTN 


LERAD 


X 


X 


X 


X 


Address 


LERAD=LERTN 


LOGON 


X 


X 


X 


X 


Address 


LOGON=LGNRTN 


LOSTERM 


X 


X 


X 


X 


Address 


LOSTERM=(6) 


RELREQ 


X 


X 


X 


X 


Address 


RELREQ=(S,AREA1) 


SYNAD 


X 


X 


X 


X 


Address 


SYNAD=(*,AREA2) 


TPEND 


X 


X 


X 


X 


Address 


TPEND=(S,4(7)) 


EXLLEN 






X 


X 


Quantity 


EXLLEN=(3) 



Figure E-3. Manipulative Macro Instruction Operands for EXLST Fields 



Address 



These notation categories are to be interpreted as follows: 
You can code any of the following expressions after the keyword and equal-sign: 
• Any expression that is valid for an A-type address constant. For example: 
MODCB ACB=ACB1 ,APPLID=NAME1 ,AM=VTAM 



NAME 



DC 
DC 



X'07' 
CL7'INQUIRY' 
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Operand 
Keyword 


GENCB 


Va 
MODCB 


lid for 
SHOWCB 


TESTCB 


Notation Category 


Example 


AAREA 


X 


X 


X 


X 


Address 


AAREA=INAREA 


AAREALN 


X 


X 


X 


X 


Quantity 


AAREALN=100 


ACB 


X 


X 


X 


X 


Address 


ACB=ACB1 


AREA 


X 


X 


X 


X 


Address 


AREA=(*,FLWORD) 


AREALEN 


X 


X 


X 


X 


Quantity 


AREALEN=132 


ARECLEN 


X 


X 


X 


X 


Quantity 


ARECLEN=(S,QUANT1) 


ARG 


X 


X 


X 


X 


Register- Indirect Value 


ARG=(7) 


BRACKET 


X 


X 




X 


Fixed Value 


BRACKET=(BB,NEB) 


BRANCH 


X 


X 




X 


Fixed Value 


BRANCH=YES 


CHAIN 


X 


X 




X 


Fixed Value 


CHAIN=LAST 


CHNGDIR 


X 


X 




X 


Fixed Value 


CHNGDIR=(CMD,NREQ) 


CONTROL 


X 


X 




X 


Fixed Value 


CONTROL=QEC 


DATAFLG 








X 


Fixed Value 


DATAFLG=EOM 


ECB 


X 


X 


X 


X 


Address 


ECB=FULLWORD 


EXIT 


X 


X 


X 


X 


Address 


EXIT=EXITRTN 


FDBK 






X 


X 


Quantity 


FDBK=(4) 


FDBK2 






X 


X 


Quantity 


FDBK2=128 


IBSQAC 


X 


X 




X 


Fixed Value 


IBSQAC=TESTPOS 


IBSQVAL 


X 


X 


X 


X 


Quantity 


IBSQVAL=0 


10 








X 


Fixed Value 


IO=COMPLETE 


NIB 


X 


X 


X 


X 


Address 


NIB=NIB6 


OBSQAC 


X 


X 




X 


Fixed Value 


OBSQAC=INVALID 


OBSQVAL 


X 


X 


X 


X 


Quantity 


0BSQVAL=(4) 


OPTCD 


X 


X 




X 


Fixed Value 


OPTCD=(SYN,SPEC) 


POST 


X 


X 




X 


Fixed Value 


POST=SCHED 


RECLEN 


X 


X 


X 


X 


Quantity 


RECLEN=32 


RESPOND 


X 


X 




X 


Fixed Value 


RESPOND=(NEX,FME) 


REQ 






X 


X 


Quantity 


REQ=VAL23 


RPLLEN 






X 


X 


Quantity 


RPLLEN=(7) 


RTNCD 






X 


X 


Quantity 


RTNCD=(*,0(3)) 


RTYPE 


X 


X 




X 


Fixed Value 


RTYPE=(NDFSYN,DFASY) 


SENSE 






X 


X 


Quantity 


SENSE=(REG3) 


SEQNO 


X 


X 


X 


X 


Quantity 


SEQNO=(10) 


SI G DATA 






X 


X 


Quantity 


SIGDATA=32,767 


SSENSEI 








X 


Fixed Value 


SSENSEI=CPM 


SSENSEO 


X 


X 




X 


Fixed Value 


SSENSEO=STATE 


SSENSMI 






X 


X 


Quantity 


SSENSM 1=255 


SSENSMO 


X 


X 


X 


X 


Quantity 


SSENSMO=(*,0(12)) 


STYPE 


X 


X 




X 


Fixed Value 


STYPE=REQ 


USENSEI 






X 


X 


Quantity 


USENSE 1=4095 


USENSEO 


X 


X 


X 


X 


Quantity 


USENSEO=(4) 


USER 






X 


X 


Quantity 


USER=1024 



Figure E-4. Manipulative Macro Instruction Operands for RPL Fields 
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Operand 
Keyword 


GENCB 


Valid 1 
MODCB 


For 
SHOWCB 


TESTCB 


Notation Category 


Example 


CID 






X 


X 


Register-Indirect Value 


CID=(7) 


CON 








X 


Fixed Value 


CON=YES 


DEVCHAR 






X 


X 


Indirect Value 


DEVCHAR=(*,0(5)) 


EXLST 


X 


X 


X 


X 


Address 


EXLST=(*,EXLSTADR) 


LISTEND 


X 


X 




X 


Fixed Value 


LISTEND=NO 


MODE 


X 


X 


X 


X 


Fixed Value 


MODE=RECORD 


NAME 


X 


X 


X 


X 


Name 


NAME=NYCTERM 


NIBLEN 






X 


X 


Quantity 


NIBLEN=(8) 


PROC 


X 


X 




X 


Fixed Value 


PROC=(EIB,ELC) 


RESPLIM 


X 


X 


X 


X 


Quantity 


RESPLIM=10 


SDT 


X 


X 




X 


Fixed Value 


SDT=SYSTEM 


USERFLD 


X 


X 


X 


X 


Quantity 


USERFLD=(9) 



Figure E-5. Manipulative Macro Instruction Operands for NIB Fields 



® A register number or the label of an EQU instruction for the register, enclosed in 
parentheses. For example: 

L 3,ADRNAME 

MODCB ACB=ACB1,APPLID=(3),AM=VTAM 



ADRNAME DC 



A(NAME1) 



Note: This form is prohibited if you are using the "simple" list form of the 
macro instruction (MF=L). List forms are explained in Appendix F. 

An expression of the form (S,expr) where expr is any expression valid for an 
S-type address constant. This form of operand specification is especially useful 
for gaining access to a control block field via a DSECT. For example, the 
program has used GENCB to build an ACB in dynamically allocated storage, and 
has placed the address of the ACB in register 5: 

USING ACBMAP,5 

MODCB ACB=(5),APPLID=(S,APPL1),AM=VTAM 



APPL1 


DC 


X'08' 




DC 


CL8'STOKQUOT' 


ACBMAP 


DSECT 
ACB 





Note: This form is prohibited if you are using the "simple" list form of the 
macro instruction (MF=L). 
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An expression of the form (*,expr) where expr is any expression valid for an 
S-type address constant. The address specified by expr is indirect; that is, it is 
the address of a fullword that contains the operand. For example, the program 
has determined which APPLID address is to be used, and has primed register 5 
with the appropriate displacement into APPLIST: 

L 7,APPLIST(5) 

MODCB ACB=ACB1 ,APPLID=(* ,(7)),AM=VTAM 



APPLIST 



EQU 

DC 

DC 



A(APPLl) 
A(APPL2) 



Quantity 



You can code any of the following expressions after the keyword and equals sign: 

• A decimal number, or an expression that you have equated to a decimal number. 
For example : 

TESTCB ACB=ACBl,ERROR=13,AM=VTAM 

• A register number, or the label of an EQU instruction for the register number, 
enclosed in parentheses. For example: 

L 5/TESTVAL 

TESTCB ACB=ACBl,ERROR=(5) 



TESTVAL DS 



(TESTVAL SET DURING PROGRAM 
EXECUTION) 



Note This form is prohibited if you are using the "simple" list form of the 
macro instruction (MF=L). 

An expression of the form (S,expr) where expr is any expression valid for an 
S-type address constant. This form is especially useful for gaining access to a 
control block field via a DSECT. For example, the program has used GENCB to 
build an ACB in dynamically allocated storage, and has placed the address of the 
ACBin register 5: 

USING ACBMAP,5 

TESTCB ACB=(5),ERROR=(S. 1 52),AM=VTAM 



ACBMAP 



DSECT 
ACB 



Note: This form is prohibited if you are using the 
macro instruction (MF=L). 



'simple" list form of the 



An expression of the form (*,expr) where expr is any expression valid for an 
S-type address constant. The address specified by expr is indirect; that is, it is 
the address of a fullword that contains the quantity for the operand. For 
example, the program has determined which ERROR value is to be tested and 
has primed register 5 with the appropriate displacement into ERRORLST: 
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L 7,ERRORLST(5) 

TESTCB ACB=ACB1 ,ERROR=(* ,ERR0RLST(5)),, 

AM=VTAM 



ERRORLST EQU 


* 


BADNAME DC 


F'90' 


BADPSWD DC 


F152' 



Fixed Value 



You can code only the expressions that are specified in the macro instruction 
descriptions. For example: 



GENCB 



BLK=ACB,MACRF=NLOGON,AM=VTAM 



Name 



You can code any of the following expressions: 

• One to eight EBCDIC characters. For example: 

TESTCB NIB=NIB 1 ,N AME=TERM0003 , AM=VT AM 

• An expression of the form (*,expr) as explained above. The address specified by 
expr is indirect; that is, it is the address of a doubleword containing the name. 
The name must be left-justified and padded to the right with blanks if it does 
not occupy the entire doubleword. For example: 

L 7,NAMEPOOL 

ST 7,NEWNAME+4 

MODCB NIB=NIB1 ,NAME(*,NEWNAME),AM=VTAM 



NEWNAME DC 
NAMEPOOL DC 



CL8TERM' 

cu'ooor 



Register-Indirect Value 



You can code any of the following expressions: 

• A register number or label of an EQU instruction for the register number, 
enclosed in parentheses. For example: 



MODCB 



RPL=RPL1 ,ARG=(REG5) 



REG5 



EQU 



Note: This form is prohibited if you are using the "simple" list form of the 
macro instruction (MF=L). 

An expression of the form (*,expr) as explained above. The address specified by 
expr is indirect; that is, it is the address of a fullword that contains the value. 
For example : 
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MODCB RPL=RPL1 ,ARG=(*, NEWCID), AM=VT AM 



NEWCID DS F (NEWCID SET DURING PROGRAM 

EXECUTION) 



Indirect Value You can code only the following expression: 



• An expression of the form (*,expr) as explained above. The address specified by 
expr is indirect; that is, it is the address of a fullword that contains the value. 
For example : 

TESTCB NIB=NIB1 ,DEVCHAR=(*,DEVMASK), 

AM=VTAM 



DEVMASK DS D (DEVMASK SET DURING PROGRAM 

EXECUTION) 
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APPENDIX F. 



LIST, GENERATE, AND EXECUTE FORMS OF THE 
MANIPULATIVE MACRO INSTRUCTIONS 



The standard form of a manipulative macro instruction expands at assembly time 
into (1) nonexecutable code that represents the parameters you specified on the 
macro instruction, and (2) executable code that causes the access method to be 
entered when the macro instruction is executed. The nonexecutable code, called 
the parameter list, is assembled at the point in your application program where the 
macro instruction appears. 

Various nonstandard forms of the manipulative macro instructions cause the 
assembler to: 

• Build the parameter list where the macro instruction appears in your source code 
but assemble no executable code ("simple" list form) 

• Assemble code that will build the parameter list at a location of your selection 
but assemble no executable code that causes the access method to be entered 
("remote" list form) 

• Assemble code that will build the parameter list at a location of your selection 
and assemble the code that causes the access method to be entered (generate 
form) 

• Assemble code that will modify a parameter list and cause the access method to 
be entered during program execution (execute form) 

Figure F-l summarizes the actions of these various forms. It also indicates the types 
of programs that would use each form, and shows how the MF operand is used for 
each form. 

As indicated in Figure F-l, the various nonstandard forms of the manipulative 
macro instructions are designated with the MF operand. 



Form 


During Assembly 


During Execution 


Useful for 


Coded with 


Standard 


Parameter list built 
where macro appears 
in source code 


Access method entered 


Nonreenterable programs 
that are not sharing or 
modifying parameter lists 


No MF operand 


"Simple" 
List 


Parameter list built 
where macro appears 
in source code 


No executable code 
(execute form required) 


Nonreenterable programs 
that are sharing or 
modifying parameter lists 


MF=L 


"Remote" 
List 


Code assembled to 
build parameter list at a 
location you specify 


Parameter list built, but 
access method not 
entered (execute form 
required) 


Reenterable programs that 
are sharing or modifying 
parameter lists 


MF=(L,address[,label]) 


Generate 


Code assembled to 
(1) build parameter list 
at a location you 
specify, and (2) enter 
the access method 


Parameter list built and 
access method entered 


Reenterable programs that 
are not sharing or 
modifying parameter lists 


MF=(G,address[,label]) 


Execute 


Code assembled (where 
macro appears in the 
source code) to modify 
the parameter list 
whose address you 
supply 


Parameter list 
modified and the access 
method entered 


Programs using the list 
form 


MF=(E,address) 



Figure F-l. The Forms of the Manipulative Macro Instructions 
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The MF operand for the list form of any manipulative macro instruction is coded as 
follows: 

MF= {L | (L,address[, label] )} 

L L 

Indicates that this is the list form of the macro instruction. If you code just MF=L 
("simple" list form), the parameter list is assembled in place. If you modify the 
parameter list during program execution, your program is not reenterable. 

address 

Indicates the location where you want the parameter list to be built during program 
execution. This area must begin on a fullword boundary and if your program is to 
be reenterable, must be in dynamically allocated storage. Since the assembler will 
build executable code that will in turn build the parameter list, the macro 
instruction must be in the executable portion of your program— that is, not treated 
as a program constant. 

You can code this address in any of the forms of the "address" notation category 
(described in Appendix E). The notes there stating that register expressions are 
prohibited for the list form do not however apply to the MF operand; this 
restriction is true only for all the other operands of the macro instruction's list 
form. For example, MF=(L,(6)) is valid. 

label 

This is a unique name that is used as a label for an assembled EQU instruction. 
During program assembly, the assembler equates this label to the length (in bytes) 
of the parameter list that will be built during program execution. You can use this 
label to assure that you are obtaining enough dynamically allocated storage to hold 
the parameter list. 

When coding label follow the same rules that apply to any label for an assembler 
instruction. 

list form example : 

LA 10,PLISTLEN OBTAIN LENGTH OF PARAMETER LIST 

GETM AIN R,LV=(1 0) OBTAIN STORAGE FOR PARAMETER LIST 

LR 5,1 SAVE STORAGE ADDRESS 

TESTCB RPL=RPLl,DATAFLG=EOM,AM=VTAM, 
MF=(L,(5),PLISTLEN) 

The MF operand for the generate form of any of the manipulative macro 
instructions is coded as follows: 

MF=(G,address[ 4abel] ) 

G 

Indicates that this is the generate form of the macro instruction. 

address 

Indicates the location where you want the parameter list to be built during program 
execution. Presumably, this will be in dynamically allocated storage. In both 
manner of use and manner of coding, this address is identical to the address 
described above for the list form. 
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label 

Indicates the label to be used on an EQU instruction for the length of the 
parameter list. The function of the label operand and its rules for coding are 
identical to those described above for the list form. 

Generate form example: 

LA 10,PLISTLEN OBTAIN LENGTH OF PARAMETER LIST 

GETMAIN R,LV=(10) OBTAIN STORAGE FOR PARAMETER LIST 

GENCB BLK=RPL,AM=VTAM 
MF=(G,(5),PLISTLEN) 

The MF operand for the execute form of any of the manipulative macro 
instructions is coded as follows: 

MF=(E, address) 

E 

Indicates that this is the execute form of the macro instruction. 

address 

Indicates the location of the parameter list to be used by the access method. 

The execute form allows you to modify the parameter list between the generation 
of that parameter list and the invocation of the access method routines that use the 
parameter list. Only the generate form provides a means for you to modify the 
parameter list after it has been built. 

The optional operands you specify on the generate form of a particular macro 
instruction are converted by the assembler into code that will modify a parameter 
list during execution. This code can only modify— and not expand— the parameter 
list. If the parameter list is actually a list form (as is typically the case), never refer 
to a control block field in a generate form that you did not specify in the list form. 
If you fail to observe this rule, and thereby attempt to expand the parameter list, 
the execute form will not be processed successfully, and a return code of 8 will be 
posted in register 15. 

Execute form example : 

EFORM MODCB EXLST=EXLST1,LERAD=(3),AM=VTAM 

MF=(E,LFORM) 



LFORM MODCB EXLST=0,LERAD=0,MF=L,AM=VTAM 

Optional and Required Operands that are required in the standard form of the manipulative macro 

Operands instructions may be optional in the list, generate, or execute forms or may be 

prohibited in the execute form. The meaning of the operands, however, and the 
notation used to express them, are the same. The following assembler format tables 
indicate which operands are required and which are optional for each form of each 
manipulative macro instruction. Any operand that does not appear in an assembler 
format table for a particular form is prohibited. 
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Name 


Operation 


Operands 


[symbol] 


GENCB 

List 
Form 


BLK= { ACB|EXLST|RPL|NIB } 

, AM=VTAM 
, keyword=value] ... 
, COPIES= { Hquantity } ] 
, WAREA=work area address] 
, LENGTH=work area length] 

, MF= { L|(L, address [ , label] ) } 


[symbol] 


GENCB 

Generate 
Form 


BLK= { ACB|EXLST|RPL|NIB } 
, AM=VTAM 

,COPIES=(Hquantity}] 

, keyword=value] ... 

, WAREA=work area address! 

, LENGTH=work area length] 
, MF=(G, address [ , label] ) 


[symbol] 


GENCB 

Execute 
Form 


AM=VTAM 

, keyword=value] ... 
,COPIES={ II quantity}] 
, WAREA=work area address] 
, LENGTH=work area length] 
, MF=(E, parameter list address) 



Figure F-2. Optional and Required Operands for the Nonstandard Forms 
of GENCB 
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Name 


Operation 


Operands 


[symbol] 


MODCB 


AM=VTAM 

( , ACB=acb address j 




List 


1 , EXLST=exit list address I 




Form 


J , RPL=rpl address I 
\ , NIB=nib address ) 
{ , field name=new value }... 
, MF= { L|(L, address [ , label] ) } 


[symbol] 


MODCB 


AM=VTAM 

l , ACB=acb address 1 




Generate 


/ , EXLST=exit list address V 




Form 


1 , RPL=rpl address ( 
\ , NIB=nib address / 
{ , field name=new value }... 
,MF=(G, address[, label]) 


[symbol] 


MODCB 


AM=VTAM 

/ , ACB=acb address \ 




Execute 


) , EXLST=exit list address f 




Form 


\ , RPL=rpl address T 
{ , NIB=nib address \ 
[ { , field name=new value }...] 
, MF=(E, parameter list address) 



Figure F-3. Optional and Required Operands for the Nonstandard Forms 
MODCB 
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Name 


Operation 


Operands 


[symbol] 


SHOWCB 


AM=VTAM 
( , ACB=acb address i 






List 


\ , EXLST=exit list address I 






Form 


\ , RPL=rpl address ( 
__' , NIB=nib address )_} 








, FIELDS= { field name|(field name, ...) } 






, AREA=data area address 








, LENGTH=data area length 








, MF= { L|(L, address [ , label] ) } 




[symbol] 


SHOWCB 


AM=VTAM 

( , ACB=acb address ) 






Generate 


1 , EXLST=exit list address/ 






Form 


j , RPL=rpl address C 
_ ' , NIB=nib address )_} 








, FIELDS= { field name|(field name, ...)} 






, AREA=data area address 








, LENGTH=data area length 








, MF=(G, address [ , label] ) 




[symbol] 


SHOWCB 


AM=VTAM 
~( , ACB=acb address \ 






Execute 


} , EXLST=exit list address ( 






Form 


J , RPL=rpl address ( 
_* , NIB=nib address J_ 
[ , AREA=data area address] 
, MF=(E, parameter list address) 





Figure F-4. Optional and Required Operands for the Nonstandard Forms 
of SHOWCB 
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Name 


Operation 


Operands 


[symbol] 


TESTCB 


AM=VTAM 
(, ACB=acb address \ 




List 


\ , EXLST=exit list address f 




Form 


J , RPL=rpl address I 
' , NIB=nib address j 
, field name=test value 
[ , ERET=error routine address] 
, MF= { L|(L, address [ , label] ) } 


[symbol] 


TESTCB 


AM=VTAM 






~Y, ACB=acb address } — 






Generate 


) , EXLST=exit list address f 






Form 


J , RPL=rpl address f 
_( , NIB=nib address ) 








, field name=test value 






[ , ERET=error routine address] 






, MF=(G, address [ , label] ) 


[symbol] 


TESTCB 


AM=VTAM 






( , ACB=acb address j 






Execute 


) , EXLST=exit list address f 






Form 


J , RPL=rpl address I 
_( , NIB=nib address )_ 








, field name=test value] 






, ERET=error routine address] 






, MF=(E, parameter list address) 



Figure F-5. Optional and Required Operands for the Nonstandard Forms 
of TESTCB 
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APPENDIX G. SUMMARY OF REGISTER USAGE 



The following table shows what VTAM does with the general-purpose registers 
before it returns control to the application program at the next sequential 
instruction. It indicates which registers are left unchanged by the VTAM macro 
instructions and which ones may be modified between the time the macro 
instruction is executed and control is returned to the application program. The 
table also shows the disposition of the registers when any of the exit-routines 
receives control. 





Register 


Register 1 


Registers 2-12 


Register 13 


Register 14 


Register 15 


Upon return from 
OPEN and CLOSE 


Unpredictable 


Unpredictable 


Unmodified 


i 
Unmodified 


Unpredictable 


Return 
code 


macros 














Upon return from 
R PL-based macros, 
including CHECK 


2 


Address of 
RPL 


Unmodified 


Unmodified 


Unpredictable 


2 


Upon return from 
GENCB 


Error return 
code or 
control block 

length 3 


Control block 
address 


Unmodified 


Unmodified 1 


Unpredictable 


General 

return 

code 


Upon return from 
SHOWCB 


Error return 
code 


Unpredictable 


Unmodified 


Unmodified 


Unpredictable 


General 

return 

code 


Upon return from 
MODCB or 
TESTCB 


Error return 
code 


Unpredictable 


Unmodified 


i 
Unmodified 


Unpredictable 


General 

return 

code 


Upon invocation 
of the LERADor 
SYNAD exit- 


Recovery 
action return 
code 


Address of 
RPL 


Unmodified 
since request 
issued 




Return 
address 


Address 
of exit- 
routine 


routine 














Upon invocation 
of the other exit- 


Unpredictable 


Address of 
VTAM- 


Unpredictable 




Return 
address 


Address 
of exit- 


routine 




supplied 
parameter list 








routine 



Register 13 must indicate the address of an 18-word save area when the macro instruction is executed. 

If the operation completed normally, register 15 is set to 0. (For some macros completing normally but with a special 
condition, register is also set - - see Appendix C.) If an error occurred and the LERAD or SYNAD exit-routine has 
been invoked, registers and 1 5 contain the values set in them by the exit-routine. If an error occurred and no LERAD 
or SYNAD exit-routine exists, VTAM sets register 15 to 4 or 32 (decimal) and places a recovery action return 
code in register 0. 

When GENCB is used to build control blocks in dynamically allocated storage and GENCB is completed successfully 
(register 15 set to 0), register 1 contains the address of the generated control blocks and register contains the length 
of the control blocks, in bytes. If GENCB is completed unsuccessfully (register 1 5 set to 4), register contains an 
error return code and register 1 is unpredictable. If GENCB is completed unsuccessfully (register 15 set to 8), no error 
return code is set in register 0. 

If SHOWCB, MODCB, or TESTCB is completed unsuccessfully (with register 15 set to 4), register contains an error 
return code. If the macro instruction is completed unsuccessfully (with register 15 set to 8), no error return code is set 
in register 0. If the macro instruction is completed successfully (with register 15 set to 0), no particular value is set in 
register (although it may have been modified by the macro instruction). 



Figure G-l . Register Contents Upon Return of Control 
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APPENDIX H. CONTROL BLOCK FORMATS AND DSECTs 



The ACB, EXLST, RPL, and NIB can be initialized, modified, and examined either 
with manipulative macro instructions (GENCB, MODCB, SHOWCB, TESTCB) or 
with assembler instructions. Manipulation via assembler instructions requires access 
to the internal structure of the control block, because displacements and bit 
settings must be incorporated into the assembler instructions. However, bit settings 
and displacements are subject to change from release to release; to avoid recoding 
assembler instructions- when such changes occur, a DSECT should be used. 
IBM-supplied DSECTs are provided as part of the VTAM macro library. They are 
described in this appendix. 

A DSECT is an overlay (map) containing labels that correspond to field 
displacements, bit settings, and byte values. 

A field displacement is the displacement of a field from the beginning of the 
control block, as defined by the DS (or ORG) instructions in the DSECT. A bit 
setting is an assembler EQU instruction (such as LABEL 1 EQU X'80') that 
identifies a particular bit or bits. The label could be used as the immediate data 
byte in a TM instruction, for example. A byte value is also an assembler EQU 
instruction (such as LABEL2 EQU X'23') that identifies a particular value in a 
byte. The label could be used as the immediate data byte of a CLI instruction, for 
example. 

The general manner in which DSECTs are used (register preparation, USING 
instructions, etc.) is described in "The DSECT Instruction" in OS/VS and DOS/VS 
Assembler Language, GC334010. 



The figures in this appendix show the format of the control blocks. They provide a 
means by which a dump of the control block can be interpteted and they make the 
DSECT descriptions that accompany them more easily understood. The following 
formats and DSECTs are described: 



Control Block 

DOS/VS ACB 
OS/VS ACB 

EXLST 

DOS/VS RPL 

OS/VS RPL 



NIB 



DSECTName* 

IFGACB 
IFGACB 

IFGEXLST 

IFGRPL 

IFGRPL 
ISTUSFBC 

ISTDNIB 
ISTDVCHR** 



(This is a separate DSECT for the RPL's 
RTNCD, FDBK, and FDBK2 fields.) 



(This is a separate DSECT for the NIB's 
DEVCHAR field.) 
ISTDPROC* * (This is a separate DSECT for the NIB's 
PROC field.) 
*This is the name you code in your program to assemble the DSECT. 
**If the DSECT for the entire NIB is used (ISTDNIB), the DSECT for this field is 
included automatically and should not be specified. 



The format maps and the DSECT descriptions identify both the external field name 
(the declarative or manipulative macro keyword as used throughout this manual) 
and the internal field name (DSECT label) for each control block field. The DSECT 
descriptions are arranged in alphabetical order according to the external field name. 
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If you compare listings of the actual DSECTs with the DSECT descriptions 
provided here, you will note that the actual DSECTs are more extensive. The fields 
that have been eliminated here are primarily fields that are set and used by VTAM, 
not by the application program. The control block fields that you set or examine 
should be limited to those fields that are included in the DSECT descriptions in this 
manual. (For this reason, you should not use a DSECT to initialize a control block; 
use GENCB or the appropriate ACB, EXLST, RPL, or NIB macro instruction 
instead.) 



Displacement 

Dec Hex 




Control Block: ACB 



16 10 



20 14 



36 24 



48 30 



ACBLEN 
(ACBLENG) 



APPLID 
(ACBAPID) 



OF LAGS 
(ACBOFLGS) 



AM 
(ACB AM) 



MACRF 
(ACBMACR2) 



ERROR 
(ACBERFLG) 



PASSWD 
(ACBPASSW) 



EXLST 
(ACBUEL) 



The names in parentheses are the labels for the ACB's DSECT (IFGACB) 
Figure H-l. The Format of the DOS/VS ACB 
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Displacement 

Dec Hex 




Control Block: ACB 



12 



32 20 

36 24 

40 28 

48 30 



72 48 







ACBLEN 
(ACBLENG) 








MACRF 
(ACBMACR2) 








PASSWD 
(ACBPASSW) 


EXLST 
(ACBUEL) 




AM 
(ACBAM) 








OF LAGS 
(ACBOFLGS) 


ERROR 
(ACBERFLG) 








APPLID 
(ACBAPID) 



The names in parentheses are the labels for the ACB's DSECT (IFGACB) 



Figure H-2. The Format of the OS/VS ACB 
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ACBDSECT: IFGACB 





DSECT 


DSECT 




Meaning (For EQU, meaning 


DOS/VS 


OS/VS 


Field 


DSorORG 


EQU 


Value 


when bit setting is on or 


Displacement 


Displacement 




label 


label 




when byte value is set) 


Dec 


Hex 


Dec Hex 


ACBLEN 


ACBLENG 


— 


_ 


ACB length 


2 


2 


2 


2 


AM 


ACBAM 


ACBVTAM 


XW 


AM=VTAM (after OPEN) 


22 


16 


43 


2B 


APPLID 


ACBAPID 


- 


- 


APPLID address 


4 


4 


72 


48 


ERROR 


ACBERFLG 


ACBOALR 

ACBCALR 

ACBNSTOR 

ACBINCPW 

ACBCDSNR 

ACBNMAIN 

ACBNJSTP 

ACBOANAT 

ACBOAHLT 

ACBOAVFY 

ACBOANSN 

ACBOAPAA 

ACBOAPNM 

ACBOVINA 

ACBOAPSE 

ACBOUNDF 

ACBOAPLE 

ACBOPWSE 

ACBOPWLE 


X'04' 
X'08' 
X'14' 
X'24' 
X'42' 
X'46' 
X'48' 
X'50' 
X'52' 
X'54' 
X'56' 
X'58' 
X'5A' 
X'5C 
X'5E' 
X'60' 
X'62' 
X'64' 
X'66' 


Already open (OPEN) 

Already closed (CLOSE) 

Not enough storage (OPEN 

Incorrect password (OPEN) 

Some connections not released (CLOSE) 

OPEN/CLOSE not in mainline 

OPEN/CLOSE not in OS job step task 

VTAM not active (OPEN/CLOSE) 

VTAM is halting (OPEN) 

APPLID is invalid (OPEN) 

APPLID is name of non-APPL (OPEN) 

APPL is already active (OPEN) 

No matching APPL found (OPEN) 

VTAM in system but inactive 

APPID not is requestor's space 

Undefined system error 

APPLID length too small - 

Password not in requestor's space 

Password length invalid 


23 


17 


49 


31 


EXLST 


ACBUEL 


- 


- 


EXLST address 


48 


30 


36 


24 


MACRF 


ACBMACR2 


ACBLOGON 


X'08' 


MACRF =NLOGON 


19 


13 


13 


D 


OFLAGS 


ACBOFLGS 


ACBOPEN 


X'10' 


OFLAGS=OPEN 


21 


15 


48 


30 


PASSWD 


ACBPASSW 


- 


- 


Password value 


36 


24 


32 


20 



Figure H-3. The DOS/VS and OS/VS ACB DSECT (IFGACB) 
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Displacement 

Dec Hex 





8 8 

12 C 

16 10 

20 14 

24 18 

28 1C 

32 20 

36 24 

40 28 

44 2C 

48 30 

52 34 



Control Block: EXLST 



56 


38 


60 


3C 


64 


40 


68 


44 







EXLLEN 
(EXLLEN2) 








SYNAD 

attributes 

(EXLSYNF) 


SYNAD 

address 

(EXLSYNP) 




LERAD 

attributes 

(EXLLERF) 


LERAD address 
(EXLLERP) 


SCIP 

attributes 

(EXLSCIPF) 


SCIP address 
(EXLSCIPP) 




LOGON 

attributes 

(EXLLGNF) 


LOGON address 
(EXLLGNP) 




DFASY 

attributes 

(EXLDFASF) 


DFASY 
address 


(EXLDFASP) 


RESP 

attributes 

(EXLRESPF) 


RESP address 
(EXLRESPP) 


LOSTERM 

attributes 

(EXLNLGNF) 


LOSTERM address 
(EXLNLGNP) 




RELREQ 
attributes 
(EXLRLRQP) 


RELREQ address 
(EXLRLRQP) 












ATTN 

attributes 

(EXLATTNF) 


ATTN address 
(EXLATTNP) 


TPEND 

attributes 

(EXLTPNDF) 


TPEND address 
(EXLTPNDP) 







The names in parentheses are the labels for the EXLST's DSECT (IFGEXLST) 



Figure H-4. The Format of the DOS/VS and OS/VS EXLST 
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EXLST DSECT: IFGEXLST 



Field 


DSECT 
DSorORG 

label 


DSECT 
EQU 
label 


Value 


Meaning (For EQU, meaning 

when bit setting is on or 

when byte value is set) 


DOS/VS 
Displacement 
Dec Hex 


OS/VS 
Displacement 
Dec Hex 


ATTN 


EXLATTNF 
EXLATTNP 


EXLATTNS 


X'80' 


ATTN exit present 
ATTN exit address 


55 
56 


37 
38 


55 
56 


37 
38 


DFASY 


EXLDFASF 
EXLDFASP 


EXLDFASS 


X'80' 


DFASY exit present 
DFASY exit address 


30 
31 


IE 
IF 


30 
31 


IE 
IF 


EXLLEN 


EXLLEN2 


- 


- 


EXLST length 


2 


2 


2 


2 


LERAD 


EXLLERF 
EXLLERP 


EXLLERS 


X'80' 


LERAD exit present 
LERAD exit address 


15 
16 


F 

10 


15 
16 


F 

10 


LOGON 


EXLLGNF 
EXLLGNP 


EXLLGNS 


X'80' 


LOGON exit present 
LOGON exit address 


25 
26 


19 
1A 


25 
26 


19 
1A 


LOSTERM 


EXLNLGNF 
EXLNLGNP 


EXLNLGNS 


X'80' 


LOSTERM exit present 
LOSTERM exit address 


40 
41 


28 
29 


40 
41 


28 
29 


RELREQ 


EXLRLRQF 
EXLRLRQP 


EXLRLRQS 


X'80' 


RELREQ exit present 
RELREQ exit address 


45 
46 


2D 
2E 


45 
46 


2D 

2E 


RESP 


EXLRESPF 
EXLRESPP 


EXLRESPS 


X'80' 


RESP exit present 
RESP exit address 


35 
36 


23 
24 


35 
36 


23 
24 


SCIP 


EXLSCIPF 
EXLSCIPP 


EXLSCIPS 


X'80' 


SCIP exit present 
SCIP exit address 


20 
21 


14 
15 


20 
21 


14 
15 


SYNAD 


EXLSYNF 
EXLSYNP 


EXLSYNS 


X'80' 


SYNAD exit present 
SYNAD exit address 


10 
11 


A 
B 


10 
11 


A 
B 


TPEND 


EXLTPNDF 
EXLTPNDP 


EXLTPNDS 


X'80' 


TPEND exit present 
TPEND exit address 


60 
61 


3C 
3D 


60 
61 


3C 
3D 



Figure H-5. The DOS/VS and OS/VS EXLST DSECT (IFGEXLST) 
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Displacement 

Dec Hex 




Control Block: RPL 



8 


8 


12 


C 


16 


10 


20 


14 


24 


18 


28 


1C 


32 


20 


36 


24 


40 


28 


44 


2C 


48 


30 


52 


34 


56 


38 


60 


3C 


64 


40 


68 


44 


72 


48 


76 


4C 


80 


50 


84 


54 


88 


58 


92 


5C 


Figure H-6. 





CHECK 
(RPLACTIV) 




RPLLEN 
(RPLLEN2) 










NIB-ARG 
(RPLARG) 


AREA 
(RPLAREA) 


RECLEN 
(RPLRLEN) 


AREALEN 
(RPLBUFL) 


ACB 
(RPLDACB) 




REQ 
(RPLREQ) 






OPTCD 
(RPLOPT1) 




EXIT 

attributes 

(RPLEXTDS) 






RTNCD 
(RPLRTNCD) 


FDBK2 
(RPLFDB2) 


DATAFLG- 

FDBK 

(RPLFDB3) 


AAREA 
(RPLAAREA) 


ECB-EXIT 
(RPLECB) 


AAREALN 
(RPLAARLN) 


ARECLEN 
(RPLARCLN) 


^ TN' 


5E-SIGDATA (RPLFDBK2-RPLSIG 
SSENSMI USENS 
(RPLSSMI) | (RPLU 


n/\ \ ^- 


SSENSEI 
(RPLSSEI) 


El 
5NSI) 


USER 
(RPLUSFLD) 


OPTCD 
(RPLOPT5) 


OPTCD 
(RPLOPT6) 


OPTCD 
(RPLOPT 7) 


OPTCD 
(RPLOPT8) 


OPTCD 
(RPLOPT9) 




OPTCD 
(RPLOPT11) 


OPTCD 
(RPLOPT12) 


BRACKET- 

CHNGDIR 

(RPLRH3) 


STYPE- 
RTYPE 
(RPLSRTYP) 




POST- 
RESPOND 
(RPLVTFL2) 


CHAIN 
(RPLCHN) 


CONTROL(I) 
(RPLCNTDF) 


CONTROU2) 
(RPLCNTDC) 


CONTROLS) 
(RPLCNTSC) 


OBSQVAL 
(RPLOBSQV) 


IBSQVAL 
(RPLIBSQV) 


OBSQAC 
(RPLOBSQ) 


IBSQAC 
(RPLIBSQ) 


SEQNO 
(RPLSEQNO) 


SSENSEO 
(RPLSSEO) 


SSENSMO 
(RPLSSMO) 


USENSEO 
(RPLUSNSO) 



The names in parentheses are the labels for the RPL's DSECT (IFGRPL) 
The Format of the DOS/VS RPL 
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Displacement 

Dec Hex 




Control Block: RPL 



8 8 



12 



16 10 



20 14 



24 18 



28 1C 



32 


20 


36 


24 


40 


28 


44 


2C 


48 


30 


52 


34 


56 


38 


60 


3C 


64 


40 


68 


44 


72 


48 



76 4C 

80 50 

84 54 

88 58 



REQ 
(RPLREQ) 



RPLLEN 
(RPLLEN2) 



ECB-EXIT 
(RPLECB) 



BRACKET- 

CHNGDIR 

(RPLRH3) 



POST-RESPOND 
(RPLVTFL2) 



RTNCD 
(RPLRTNCD) 



STYPE- 
RTYPE 
(RPLSRTYP) 



(RPLFDBK) 

FDBK2 

(RPLFDB2) 



CHAIN 
(RPLCHN) 



DATAFLG-FDBK 
(RPLFDB3) 



CONTROL (RPLCNTRL) 



(RPLCNTDF) | (RPLCHTDC) [ (RPLCNTSC) 



ACB 
(RPLDACB) 



AREA 
(RPLAREA) 



NIB-ARG 
(RPLARG) 



OPTCD 
(RPLOPTI) 



RECLEN 
(RPLRLEN) 



AREALEN 
(RPLBUFL) 



OPTCD 
(RPLOPT5) 



OPTCD 
(RPLOPT6) 



OBSQVAL 
(RPLOBSQV) 



OBSQAC 
(RPLOBSQ) 



EXIT 

attributes 

(RPLEXTDS) 



IBSQAC 
(RPLIBSQ) 



CHECK 
(RPLACTIV) 



OPTCD 
(RPLOPT7) 



OPTCD 
(RPLOPT8) 



IBSQVAL 
(RPLIBSQV) 



SEQNO 
(RPLSEQNO) 



AAREA 
(RPLAAREA) 



AAREALN 
(RPLAARLN) 



ARECLEN 
(RPLARCLN) 



l SENSE-SIGDATA(RPLSIGDA-RPLFDBK2) 

WPL^I) I (RPLsgil) I USENSE, (RPLUSNSQ 



Figure H-7 (Part 1 of 2). The Format of the OS/VS RPL 
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Displacement 

Dec Hex 
92 5C 



96 60 



100 64 



OPTCD 
(RPLOPT9) 



SSENSEO 
(RPLSSEO) 



Control Block: RPL (Cont.) 



USER 
(RPLUSFLD) 



OPTCD 
(RPLOPT11) 



OPTCD 
(RPLOPT12) 



SSENSMO 
(RPLSSMO) 



(RPLOSENS) 



USENSEO (RPLUSNSO) 



The names in parentheses are the labels for the RPL's DSECT (IFGRPL) 



Figure H-7 (Part 2 of 2). The Format of the OS/VS RPL 
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RPLDSECT: IFGRPL 





DSECT 


DSECT 




Meaning (For EQU, meaning 


DOS/VS 


OS/VS 


Field 


DS or ORG 


EQU 


Value 


when bit setting is on or 


Displacement 


Displacement 




label 


label 




when byte value is set) 


Dec 


Hex 


Dec 


Hex 


AAREA 


RPLAAREA 


_ 


_ 


AAREA address 


40 


28 


76 


4C 


AAREALN 


RPLAARLN 


- 


- 


AAREALEN value 


48 


30 


80 


50 


ACB 


RPLDACB 


- 


- 


ACB address 


24 


18 


24 


18 


AREA 


RPLAREA 


- 


- 


AREA address 


12 


C 


32 


20 


AREALEN 


RPLBUFL 


- 


- 


AREALEN value 


20 


14 


52 


34 


ARECLEN 


RPLARCLN 


- 


- 


ARECLEN value 


52 


34 


84 


54 


BRACKET 


RPLRH3 


RPLBB 
RPLEB 


XW 
X'40' 


BRACKET=BB 
BRACKET=EB 


72 


48 


16 


10 


BRANCH 


RPLEXTDS 


RPLBRANC 


X'02' 


BRANCH=YES 


34 


22 


68 


44 


CHAIN 


RPLCHN 


RPLFIRST 
RPLMIDLE 
RPLLAST 
RPLONLY 


X'80' 
X'40' 
X'20' 
X'10' 


CHAIN=FIRST 

=MIDDLE 

=LAST 

=ONLY 


76 


4C 


18 


12 


CHECK 


RPLEXTDS 


RPLEXSCH 


X'80' 


RPL exit has been entered 


34 


22 


68 


44 




RPLACTIV 


- 


X'FF' 


RPL is active 


1 


1 


69 


45 


CHNGDIR 


RPLRH3 


RPLCMD 
RPLCHREQ 


X'20' 
X'10' 


CHNGDIR=CMD 
CHNGDIR=REQ 


72 


48 


16 


10 


CONTROL 


RPLCNTDF 


RPLDATA 


X'80' 


CONTROL=DATA 


77 


4D 


21 


15 


(all settings 




RPLCNCEL 


X'40' 


=CANCEL 










mutually 




RPLQC 


X'20' 


=QC 










exclusive) 




RPLQEC 

RPLCHASE 

RPLRELQ 


X'10' 
X'08' 
X'04' 


=QEC 

=CHASE 

=RELQ 












RPLCNTDC 


RPLBID 
RPLRTR 
RPLLUS 
RPLSIGNL 


X'80' 
X'40' 
X'20' 
X'10' 


=BID 
=RTR 
=LUS 
=SIGNAL 


78 


4E 


22 


16 




RPLCNTSC 


RPLSDT 

RPLCLEAR 

RPLSTSN 

RPLSHUTD 

RPLSHUTC 

RPLRQR 

RPLRSHUT 


X'80' 
X'40' 
X'20' 
X'10' 
X'08' 
X'04' 
X'02' 


=SDT 

=CLEAR 

=STSN 

=SHUTD 

=SHUTC 

=RQR 

=RSHUTD 


79 


4F 


23 


17 


ECB 


RPLOPT1 


RPLECBIN 


x'or 


ECB is external to the RPL 


32 


20 


40 


28 


ECB-EXIT 


RPLECB 


- 


- 


ECB, ECB address, or EXIT address 


44 


2C 


8 


8 


EXIT 


RPLEXTDS 


RPLNEXIT 
RPLEXIT 


X'40' 
X'20' 


No RPL exit specified 
RPL exit specified 


34 


22 


68 


44 


FDBK2 


RPLFDB2 






FDBK2 return code 
(see Figure H-9) 


38 


26 


14 


E 


FDBK- 


RPLFDB3 


RPLUINPT 


X'80' 


DATAFLG=UNSOL 


39 


27 


15 


F 


DATAFLG 




RPLREOB 

RPLREOM 

RPLREOT 

RPLRLG 

RPLRDSOH 


X'20' 
X'10' 
X'08' 
X'02' 

x'or 


=EOB 

=EOM 

=EOT 

=LG 

=SOH 










IBSQAC 


RPLIBSQ 


RPLISET 

RPLITST 

RPLIRSET 

RPLIIGN 

RPLIPOS 

RPLINEG 

RPLIINV 


X'80' 
X'40' 
X'20' 
X'10' 
X'08' 
X'04' 
X'02' 


IBSQAC=SET 

KTESTSET 

=RESET 

=IGNORE 

=TESTPOS 

=TESTNEG 

=INVALID 


85 


55 


65 


41 


IBSQVAL 


RPLIBSQV 


- 


- 


IBSQVAL value 


82 


52 


68 


3E 



Figure H-8 (Part 1 of 4). The DOS/VS and OS/VS RPL DSECT (IFGRPL) 
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DSECT 


DSECT 




Meaning (For EQU, meaning 


DOS/VS 


OS/VS 


Field 


DSorORG 


EQU 


Value 


when bit setting is on or 


Displacement 


Displacement 




label 


label 




when byte value is set) 


Dec 


Hex 


Dec Hex 


NIB-ARG 


RPLEXTDS 


RPLNIB 


X'04' 


RPLARG points to a NIB 


34 


22 


68 


44 




RPLARG 


— 


- 


NIB address or CIB 


8 


8 


36 


24 


OBSQAC 


RPLOBSQ 


RPLOSET 

RPLOTST 

RPLORSET 

RPLOIGN 

RPLOPOS 

RPLONEG 

RPLOINV 


xw 

X'40' 
X'20' 
X'10' 
X'08' 
X'04' 
X'02' 


OBSQAC=SET 

=TESTSET 

=RESET 

=IGNORE 

=TESTPOS 

=TESTNEG 

=INVALID 


84 


54 


64 


40 


OBSQVAL 


RPLOBSQV 


- 


- 


OBSQVAL value 


80 


50 


60 


3C 


OPTCD 


RPLOPT1 


RPLASY 


X'08' 


OPTCD=ASY 


32 


20 


40 


28 




RPLOPT5 


RPLDLGIN 

RPLPSOPT 

RPLNERAS 

RPLEAU 

RPLERACE 

RPLNODE 

RPLWROPT 


X'80' 
X'20' 
X'10' 
X'08' 
X'04' 
X'02' 

x'or 


OPTCD=CS 
OPTCD-PASS 
OPTCD=NERASE 
=EAU 
=ERASE 
OPTCD=ANY 
OPTCD=CONV 


64 


40 


56 


38 




RPLOPT6 


RPLEOB 

RPLEOM 

RPLEOT 

RPLCOND 

RPLNCOND 

RPLLOCK 


X'80' 
X'40' 
X'20' 
X'10' 
X'08' 
X'04' 


OPTCD=EOB 

=EOM 

=EOT 
OPTCD=COND 

=UNCOND 

=LOCK 


65 


41 


57 


39 




RPLOPT7 


RPLCNALL 
RPLCNANY 
RPLQOPT 
RPLRLSOP 


X'80' 
X'40' 
X'10' 
X'04' 


OPTCD=CONALL 
=CONANY 
OPTCD=Q 
OPTCD=RELRQ 


66 


42 


58 


3A 




RPLOPT8 


RPLODACQ 
RPLODACP 


X'80' 
X'40' 


OPTCD=ACQUIRE 
=ACCEPT 


67 


43 


59 


3B 




RPLOPT9 


RPLLOGON 

RPLDEVCH 

RPLTERMS 

RPLCOUNT 

RPLAPPST 

RPLCIDE 

RPLTOPL 


X'80' 
X'40' 
X'20' 
X'10' 
X'08' 
X'02' 

x'or 


OPTCD=LOGONMSG 
=DEVCHAR 
=TERMS 
=COUNTS 
=APPSTAT 
=CIDXLATE 
=TOPLOGON 


68 


44 


96 


60 




RPLOPT11 


RPLQUIES 
RPLSTART 
RPLSTOP 


X'80' 
X'40' 
X'20' 


OPTCD=QUIESCE 
=START 
=STOP 


70 


46 


98 


62 




RPLOPT12 


RPLKEEP 
RPLTRUNC 
RPLNIBTK 
RPLFMHDR 


X'40' 
X'20' 
X'10' 

x'or 


OPTCD=KEEP 
=TRUNC 
=NIBTK 
=FMHDR 


71 


47 


99 


63 


POST 


RPLVTFL2 


RPLSCHED 


X'80' 


POST=SCHED 


75 


4B 


20 


14 


RECLEN 


RPLRLEN 


- 


- 


RECLEN value 


16 


10 


48 


30 


REQ 


RPLREQ 


RPLWRITE 

RPLRESET 

RPLDO 

RPLQUISE 

RPLSMLGO 

RPLOPNDS 

RPLCHNG 

RPLINQIR 


x'ir 

X'12' 
X'13' 
X'15' 
X'16' 
X'17' 
X'19' 
X'lA' 


WRITE 

RESET 

DO 

SETLOGON 

SIMLOGON 

OPNDST 

CHANGE 

INQUIRE 


29 


ID 


2 


2 



Figure H-8 (Part 2 of 4). The DOS/VS and OS/VS RPL DSECT (IFGRPL) 
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DSECT 


DSECT 




Meaning (For EQU, meaning 


DOS/VS 


OS/VS 


Field 


DSorORG 


EQU 


Value 


when bit setting is on or 


Displacement 


Displacement 




label 


label 




when byte value is set) 


Dec 


Hex 


Dec Hex 


REQ 


RPLREQ 


RPLINTPT 

RPLREAD 

RPLSLICT 

RPLCLOSE 

RPLSNDCD 

RPLRCVCD 

RPLRSRGD 

RPLSSCCD 


X'lB' 
X'lD' 

X'lE' 
X'lF' 
X'22' 
X'23' 
X'24' 
X'25' 


INTRPRET 

READ 

SOLICIT 

CLSDST 

SEND 

RECEIVE 

RESETSR 

SESSIONC 


29 


ID 


2 


2 


RESPOND 


RPLVTFL2 


RPLEX 

RPLNFME 

RPLRRN 


X'04' 
X'02' 

x'or 


RESPOND=EX 

RESPOND=NFME 

RESPOND=RRN 


75 


4B 


20 


14 


RPLLEN 


RPLLEN2 


- 


- 


RPL length 


3 


3 


3 


3 


RTNCD 


RPLRTNCD 


RPLAOK 

RPLXORDC 

RPLRESSU 

RPLDAMGE 

RPLENVR 

RPLULGIC 

RPLRLGIC 


xw 

X'04' 
X'08' 
X'06' 
X'10' 
X'14' 
X'18' 


Normal or conditional completion 

Extraordinary completion 

Retriable 

Damage 

Environment error 

User logic error 

(Should not occur) 


37 


25 


13 


D 


RTYPE 


RPLSRTYP 


RPLRRESP 
RPLNFSYN 
RPLDFASY 


X'08' 
X'04' 
X'02' 


RTYPE=RESP 

RTYPE=NDFSYN 

RTYPE=DFASY 


73 


49 


17 


11 


SENSE 


RPLFDBK2 


- 


- 


BASIC mode input sense 


56 


38 


88 


58 


SEQNO 


RPLSEQNO 


- 


i - 


: SEQNO value 


86 


56 


66 


42 


SIGDATA 


RPLSIGDA 


- 


— 


CONTROL=SIGNAL DATA 


56 


38 


88 


58 


SSENSEI 


RPLSSEI 


RPLPATHI 

RPLCPMI 

RPLSTATI 

RPLFII 

RPLRRI 


XW 
X'40' 
X'20' 
XW 
X'08' 


SSENSEI=PATH 
=CPM 
=STATE 
=FI 
=RR 


56 


38 


88 


58 


SSENSEO 


RPLSSEO 


RPLCPMO 
RPLSTATO 
RPLFIO 
RPLRRO 


X'40' 
X'20' 
X'10' 
X'08' 


SSENSEO=CPM 

=STATE 

=FI 

=RR 


88 


58 


100 


64 


SSENSMI 


RPLSSMI 






System sense modifier value 

(see labels for SSENSMO below) 


57 


39 


89 


59 


SSENSMO 


RPLSSMO 






System sense modifier value (outgoing) 


89 


59 


101 


65 


STATE 




RPLSMSEQ 
RPLSMCHN 
RPLSMBKT 
RPLSMDIR 
RPLSMQUI 


x'or 

X'02' 
X'03' 
X'04' 
X'06' 


Sequence number error 
Chaining error 
Bracket protocol error 
Direction error 
Data sent when quiesced 










FI 




RPLSMRUD 
RPLSMRUL 
RPLSMFNS 
RPLSMRGE 
RPLSMCNS 
RPLSMFMH 


X'02' 
X'03' 
X'05' 
X'07' 
X'08' 


RU data not translatable 
RU length error 
Function not supported 
Parameter range error 
Category not supported 
Invalid FM header 










RR 




RPLSMIRQ 

RPLSMPRJ 

RPLSMBRK 

RPLSMNRR 

RPLSMRTR 

RPLSMNRQ 


X'02' 
X'OA' 

x'ir 

X'13' 
X'14' 
X'19' 


Intervention required 

Permission rejected 

Break this chain 

BID/BB - Do not wait for RTR 

BID/BB - Wait for RTR 

RTR not required 











Figure H-8 (Part 3 of 4). The DOS/VS and OS/VS RPL DSECT (IFGRPL) 
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DSECT 


DSECT 




Meaning (For EQU, meaning 


DOS/VS 


OS/VS 


Field 


DSorORG 


EQU 


Value 


when bit setting is on or 


Displacement 


Displacement 




label 


label 




when byte value is set) 


Dec Hex 


Dec Hex 


RR 




RPLSMRIX 
RPLSMFNX 


X'lB' 
X'lC 


Receiver in transmit mode 
Function not executable 










STYPE 


RPLSRTYP 


RPLSRESP 


X'80' 


STYPE=RESP 


73 


49 


17 


11 


USENSEI 


RPLUSNSI 


- 


- 


USENSEI value 


58 


3A 


90 


5A 


USENSEO 


RPLUSNSO 


- 


- 


USENSEO value 


90 


5A 


102 


66 


USER 


RPLUSFLD 


- 


- 


USER value 


60 


3C 


92 


5C 



Figure H-8 (Part 4 of 4). The DOS/VS and OS/VS RPL DSECT (IFGRPL) 
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RTNCD-FDBK-FDBK2 DSECT: ISTUSFBC 



Field 



DSECT 
DSorORG 

label 



DSECT 




EQU 


Value 


label 




USFAOK 


X'OO' 


USFXORDC 


X'04' 


USFRESSU 


X'08' 


USFDAMGE 


X'OC' 


USFENVER 


X'10' 


USFLOGIC 


X'14' 


USFRLGIC 


X'18' 


USFAOOK 


X'OO' 


USFRCWNP 


x'or 


USFRCDPR 


X'02' 


USFYTCTN 


X'03' 


USFYTCTL 


X'04' 


USFATSFI 


X'05' 


USFNOIN 


X'06' 


USFIIINA 


X'07' 


USFDSTIV 


X'08' 


USFIVLGFA 


X'09' 


USFRVIRC 


X'OO' 


USFATNRC 


x'or 


USFBSCSM 


X'02' 


USFEXRQ 


X'03' 


USFEXRS 


X'04' 


USFSTALF 


X'OO' 


USFIOEDU 


X'OO' 


USFDVUNS 


x'or 


USFUNTRM 


X'02' 


USFBTHEX 


X'03' 


USFBTEOR 


X'04' 


USFNCPAO 


X'05' 


USFLIORP 


X'06' 


USFRECIP 


X'07' 


USFRTRAF 


X'08' 


USFUSRES 


X'OA' 



Meaning (For EQU, meaning 

when bit setting is on or 

when byte value is set) 



DOS/VS 
Displacement 
Dec Hex 



OS/VS 
Displacement 
Dec Hex 



The following byte values apply to the 

RTNCD field (RPLRTNCD in the 

IFGRPL DSECT): 

Normal or conditional completion 

Extraordinary completion 

Retriable-Reissue 

Damage 

Environment error 

User logic error 

(Should not occur) 

The following byte values apply to the 

FDBK2 field (RPLFDBK2 in the 

IFGRPL DSECT) when RTNCD is set 

to X'OO': 

Normal completion 

RESET (COND) issued with I/O in 

progress 

Normal completion with data 

Yielded to contention 

Yielded to contention, error lock set 

Input area too small 

No input available 

INQUIRE information not available 

Terminal in use 

No logon requests 

The following byte values apply when 

RTNCD is set to X'04': 

RVI received 

Attention or reverse break received 

SENSE field set 

Exception condition for incoming 

message 

Incoming response indicates exception 

condition 

The following byte value applies when 
RTNCD is set to X'08': 
Temporary storage shortage 

The following byte values apply when 

RTNCD is set to X'OC': 

Error lock set 

Terminal not usable 

Request canceled by TRM 

Buffers now emptied 

Buffers filled 

NCP abended, restart successful 

NCP abended, restart successful 

(Final I/O request) 

Connection recovery in progress 

Logical unit restarted 

Request canceled by RESET or 

RESETSR 



Figure H-9 (Part 1 of 4). The RPL's RTNCD-FDBK-FDBK2 DSECT (ISTUSFBC) 
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DSECT 


DSECT 




Meaning (For EQU, meaning 


DOS/VS 


OS/VS 


Field 


DS or ORG 


EQU 


Value 


when bit setting is on or 


Displacement 


Displacement 




label 


label 




when byte value is set) 


Dec Hex 


Dec Hex 






USFCLOCC 


X'OB' 


Request canceled by CLSDST 














USFCLRED 


X'OC' 
X'OD' 


Request canceled by clear indicator 
SEND canceled due to prior exception 
condition 

The following byte values apply when 
RTNCD is set to X'10': 














USFTANAV 


X'OO' 


Terminal or APPL not available 














USFSBFAL 


x'or 


OPNDST failed for logical unit 














USFTAPUA 


X'02' 


APPL does not accept logon requests 














USFVTHAL 


X'03' 


HALT (quick) issued 














USFILRS 


X'04' 


VTAM/NCP incompatibility 














USFPCF 


X'05' 


Permanent channel failure 














USFANS 


X'06' 


Automatic NCP shutdown 














USFVOFOC 


X'07' 


Request canceled by VARY command 














USFDISCO 


X'08' 


Dial-line disconnection 














USFUTSCR 


X'09' 


Unconditional terminate self received 














USFSYERR 


X'OA' 


VTAM error 














USFDIDOL 


X'OB' 


Dial-out disconnection 














USFDIDIL 


X'OC' 


Dial-in disconnection 














USFVTMNA 


X'OD' 


VTAM inactive for APPL 














USFABNDO 


X'OE' 


Abend for APPL's TCB 

The following byte values apply when 
RTNCD is set to X' 14': 














USFNONVR 


X'OO' 


VSAM request 














USFNOTAS 


x'or 


Reserved 














USFEXTAZ 


X'02' 


Zero EXIT field 














USFEXTEZ 


X'03' 


Zero ECB field 














USFCRPLN 


X'04' 


Inactive RPL checked 














USFCBERR 


X'10' 


Control block invalid 














USFRNORT 


x'ir 


RTYPE invalid for RECEIVE 














USFCLSIP 


X'12' 


CLSDST in progress 














USFCIDNG 


X'13' 


CID invalid 














USFILDOP 


X'14' 


CMD field invalid 














USFWANCR 


X'15' 


READ LDO not chained 














USFSTOOD 


X'16' 


SOLICIT for output-only terminal 














USFRTOOD 


X'17' 


READ for output-only terminal 














USFWTOI 


X'18' 


WRITE for input-only terminal 














USFEWNS 


X'19' 


WRITE ERASE for invalid terminal 














USFEWAU3 


X'lA' 


WRITE EAU for invalid terminal 














USFCWTOO 


X'lB' 


WRITE CONV for output-only terminal 














USFCWB 


X'lC 


WRITE ERASE and CONV 














USFCCCPY 


X'lD' 


COPYLBM or COPYLBT chained 














USFIDA 


X'lE' 


Invalid data or length 














USFILDOA 


X'lF' 


LDO address invalid 














USFJTOJ 


X'20' 


Reserved 














USFMT100 


X'21' 


Reserved 














USFRILCP 


X'22' 


Reserved 














USFCRIRT 


X'23' 


Request type invalid 














USFRIOCC 


X'24' 


Invalid FLAGS for a READ LDO 














USFEWBLK 


X'25' 


WRITE ERASE and BLK 














USFCRSDC 


X'26' 


Reserved 














USFIREST 


X'27' 


RESET option invalid 














USFWBT32 


X'28' 


WRITE option invalid 











Figure H-9 (Part 2 of 4). The RPL's RTNCD-FDBK-FDBK2 DSECT (ISTUSFBC) 
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DSECT 


DSECT 




Meaning (For EQU, meaning 


DOS/VS 


OS/VS 


Field 


DSorORG 


EQU 


Value 


when bit setting is on or 


Displacement 


Displacement 




label 


label 




when byte value is set) 


Dec Hex 


Dec Hex 






USFRMD32 


X'29' 


READBUF for non-3270 terminal 














USFCTN32 


X'2A' 


COPY operation to non-3270 terminal 














USFWCNVR 


X'2B' 


WRITE CONV when data expected 














USFRNFT3 


X'2C 


Output not preceded by input 














USFRCINV 


X'2D' 


RESET COND with error lock set 














USFINVRM 


X'2E' 


BLOCK-MSG-TRANS-CONT invalid 














USFLGGNT 


X'2F' 


Too many leading graphic characters 














USFCECNT 


X'30' 


Invalid COPYLBM or COPYLBT LEN 














USFIDAEL 


X'31' 


Invalid data area 














USFUSELE 


X'32' 


Request invalid for specified area 














USFCRNF 


X'33' 


WRITE CONV reply not possible 














USFNORD 


X'34' 


First I/O not READ or SOLICIT 














USFCPYE2 


X'35' 


Terminals not on same control unit 














USFRELNP 


X'36' 


RESET LOCK invalid 














USFCPYE1 


X'37' 


Terminal not connected 














USFDFIBH 


X'38' 


Reserved 














USFDFIPO 


X'39' 


Invalid PROC option 














USFQSCIE 


X'3A' 


Reserved 














USFREXAL 


X'3B' 


NFME-NRRN response 














USFSDNP 


X'3C 


SEND SCHED still pending 














USFSCEM 


X'3D' 


Reserved 














USFSCEF 


X'3E' 


Reserved 














USFSNQC 


X'3F' 


Reserved 














USFSINVC 


X'40' 


CONTROL invalid 














USFSDFR 


X'41' 


No SDT issued 














USFSNOS 


X'42' 


Reserved 














USFSNOUT 


X'43' 


Reserved 














USFLIMEX 


X'44' 


RESPLIM exceeded 














USFSSEQ 


X'45' 


Reserved 














USFSINVS 


X'46' 


Reserved 














USFSINVR 


X'47' 


Invalid SEND for 3270 














USFINVRT 


X'48' 


Redundant clear indicator 














USFACINV 


X'49' 


Invalid STSN indicator 














USFICNDN 


X'4A' 


APPL name not available 














USFILSIN 


X'4B' 


INTRPRET sequence invalid 














USFIICBE 


X'4C 


No terminal or APPL name 














USFINTNA 


X'4D' 


No interpret table 














USFILNBL 


X'4E' 


Invalid use of a NIB list 














USFINVOT 


X'4F' 


ACQUIRE-ACCEPT invalid 














USFINVAP 


X'50' 


CONANY-CONALL invalid 














USFAPNAC 


X'51' 


APPL never accepts 














USFINVNB 


X'52' 


NIB invalid 














USFSYMNU 


X'53' 


Terminal or APPL name not found 














USFDSTUO 


X'54' 


Invalid terminal name 














USFNOPAU 


X'55' 


OPNDST ACQUIRE not authorized 














USFMPINC 


X'56' 


Invalid MODE 














USFINVMD 


X'57' 


No MODE 














USFBHSUN 


X'58' 


Reserved 














USFMDNAU 


X'59' 


Reserved 














USFMBHSS 


X'5A' 


Reserved 














USFINVLA 


X'5B' 


Invalid logon message address 














USFDUPND 


X'5C 


Duplicate terminal names 














USFDSTNO 


X'5D' 


Terminal not connected 














USFNPSAU 


X'5E' 


CLSDST PASS not authorized 














USFRSCNO 


X'5F' 


CLSDST PASS invalid 











Figure H-9 (Part 3 of 4). The RPL's RTNCD-FDBK-FDBK2 DSECT (ISTUSFBC) 
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Field 


DSECT 
DS or ORG 

label 


DSECT 
EQU 
label 


Value 


Meaning (For EQU, meaning 
when bit setting is on or 
when byte value is set) 


DOS/VS 
Displacement 
Dec Hex 


OS/VS 
Displacement 
Dec Hex 






USFRSCNC 


XW 


CLSDST RELEASE invalid 














USFINVSL 


X'61' 


SETLOGON invalid 














USFMCNVD 


X'62' 


Invalid request for MODE 














USFTACT 


XW 


The following byte values apply to the 
FDBK field (RPLFDB3 in the IFGRPL 
DSECT): 
APPL is active 














USFIINA 


X'04' 


APPL is inactive 














USFINA 
USFITNA 


X'08' 
X'OC' 


APPL never accepts logon requests 
APPL temporarily not accepting logon 














USFIQUIE 


X'lO' 


requests 

APPL no longer accepts logon requests 











Figure H-9 (Part 4 of 4). The RPL's RTNCD-FDBK-FDBK2 DSECT (ISTUSFBC) 
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Displacement 

Dec Hex 




4 

8 

12 



SeelSTDVCHR 
(Figure H12) 



See ISTDPROC . 
(Figure H13) \ 



20 14 

f 28 1C 

32 20 

36 24 

40 28 

44 2C 



General 
characteristics 



Physical 

device 

address 



PROC1 



NIB 

attributes 

(NIBFLGS) 



Control Block: NIB 



CID 
(NIBCID) 



USERFLD 
(NIBUSER) 



NAME 
(NIBSYM) 



MODE 
(NIBMODE) 



Device Type 



Model 



DEVCHAR 
(NIBDEVCH) 



PROC(NIBPROCD) 



PROC2 



PROC3 



NIBLEN 
(NIBLEN) 



Additional 
characteristics 



PROC4 



RESPLIM 
(NIBLIMIT) 



EXLST 
(NIBEXLST) 



The names in parentheses are the labels for the NIB's DSECT (ISTDNIB) 



Figure H-10. The Format of the DOS/VS and OS/VS NIB 
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NIB DSECT: ISTDNIB 



Field 


DSECT 

DSorORG 

label 


DSECT 
EQU 
label 


Value 


Meaning (For EQU, meaning 

when bit setting is on or 

when byte value is set) 


DOS/VS 
Displacement 
Dec Hex 


OS/VS 
Displacement 
Dec Hex 


CID 


NIBCID 


- 


- 


Communication ID 


4 


4 


4 


4 


CON 


NIBFLG1 


NIBCON 


X'40' 


CON=YES 


40 


28 


40 


28 


DEVCHAR 


NIBDEVCH 






(See ISTDVCHR, Figure H-12) 


28 


1C 


28 


1C 


EXLST 


NIBEXLST 


- 


- 


EXLST address 


44 


2C 


44 


2C 


LISTEND 


NIBFLG1 


NIBLAST 


X'80' 


LISTEND=NO 


40 


28 


40 


28 


MODE 


NIBMODE 


- 


- 


MODE value 


20 


14 


20 


14 


NAME 


NIBSYM 


- 


- 


NAME value 


12 


C 


12 


C 


NIBLEN 


NIBLEN 


- 


- 


NIB length 


3 


3 


3 


3 


PROC 


NIBPROCD 






(See ISTDPROC, Figure H-13) 


36 


24 


36 


24 


RESPLIM 


NIBLIMIT 


- 


- 


RESPLIM value 


42 


2A 


42 


2A 


SDT 


NIBFLG1 


NIBSDAPP 


X'20' 


SDT=APPL 


40 


28 


40 


28 


USERFLD 


NIBUSER 


- 


- 


USERFLD value 


8 


8 


8 


8 



Figure H-l 1. The DOS/VS and OS/VS NIB DSECT (ISTDNIB) 
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DEVCHAR DSECT: ISTDVCHR 





DSECT 


DSECT 




Meaning (For EQU, meaning 


DOS/VS 


OS/VS 


Field 


DSorORG 


EQU 


Value 


when bit setting is on or 


Displacement 


Displacement 




label 


label 




when byte value is set) 


Dec Hex 


Hec Hex 


DEVCHAR 


DEVSHCH 


DEVINPUT 
DEVOTPUT 
DEVCONVR 

DEVSPS 

DEVNNSPT 
DEVCCTL 


X'80' 
X'40' 
X'20' 

X'08' 

X'04' 
X'02' 


Device scheduling characteristics: 

The device is an input device; it is 
capable of sending data to the applica- 
tion program. 

The device is an output device; it is 
capable of receiving data sent to it 
from the application program. 

The device is equipped with the Conver- 
sational Mode feature. This means that 
the device can receive data instead of 
the usual positive response to the block 
of data just sent from the device. 

The device is a 3275 Display Station 
with a printer attached. 

The device is a dial-in terminal. 

Additional information is contained in 
the first half of the fourth byte 
(DEVFLAGS) 


28 


1C 


28 


1C 




DEVTCODE 


DEV2740 

DEV2741 

DEV1050 

DEVTWX 

DEVWTTY 

DEV83B3 

DEV2770 
DEV2780 
DEV3735 

DEV3780 
DEVSYS3 
DEV3704 
DEV3705 
DEV2980 
DEV3277 
DEV3284 
DEV3286 
DEV3275 
DEV3741 
DEV3747 
DEVMTA 

DEV2972 

DEV3271 

DEVCC 

DEV3272 

DEV1052 

DEV1053 

DEV1054 

DEV1055 


X'01' 
X'02' 
X'03' 
X'04' 
X'05' 
X'07' 

X'09' 
X'OA' 
X'OB' 

X'OC' 
X'13' 
X'16' 
X'17' 
X'18' 
X'19' 
X'lA' 
X'lB' 
X'lC 
X'lD' 
X'lE' 
X'28' 

X'33' 
X'34' 
X'35' 
X'36' 
X'64' 
X'65' 
X'66' 
X'67' 


The device is: 

a 2740 Communication Terminal. 

a 2741 Communication Terminal. 

a 1050 Data Communication System. 

an AT&T Teletypewriter Terminal. 

a World Trade Telegraph Station. 

an AT&T 83B3 Selective Calling 
Station. 

a 2770 Data Communication Terminal. 

a 2780 Data Transmission Terminal. 

a 3735 Programmable Buffered 
Terminal. 

a 3780 Data Transmission Terminal. 

a System/3 CPU. 

a 3704 Communications Controller. 

a 3705 Communications Controller. 

a 2980 General Banking Terminal. 

a 3277 Display Station. 

a 3284 Printer. 

a 3286 Printer. 

a 3275 Display Station. 

a 3741 Data Station (of a 3740). 

a 3747 Data Concerter (of a 3740). 

a Multiple Terminal Access (MTA) 
terminal. MTA terminals are explained 
in Network Control Program Genera- 
tion and Utilities. 

a 2972 Station Control Unit. 

a 3271 Control Unit. 

a Cluster Controller. 

a 3272 Control Unit. 

a 1052 Printer-keyboard. 

a 1053 Printer. 

a 1054 Paper Tape Reader. 

a 1055 Paper Tape Punch. 


29 


ID 


29 


ID 



Figure H-12 (Part 1 of 2). The NIB's DEVCHAR DSECT (ISTDVCHR) 
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DSECT 


DSECT 




Meaning (For EQU, meaning 


DOS/VS 


OS/VS 


Field 


DSorORG 


EQU 


Value 


when bit setting is on or 


Displacement 


Displacement 




label 


label 




when byte value is set) 


Dec Hex 


Dec Hex 


DEVCHAR 


DEVTCODE 


DEV1056 

DEV1057 

DEV1058 

DEV1092 

DEV1093 

DEVLU 

DEV545 

DEV2203 

DEV2213 

DEV2265 

DEV2502 

DEV50 

DEV5496 


X'68' 
X'69' 
X'6A' 
X'6B' 
X'6C 
X'6D' 
X'78' 
X'7B' 
X'7C 
X'7D' 
X'7E' 
X'7F' 

X'81' 


The device is: 

a 1056 Card Reader. 

a 1057 Card Punch. 

a 1058 Printing Card Punch. 

a 1092 Programmed Keyboard. 

a 1093 Programmed Keyboard. 

a Logical Unit (use record-mode). 

a 545 Output Punch (of a 2770). 

a 2203 Printer (of a 2770). 

a 2213 Printer (of a 2770). 

a 2265 Display Station. 

a 2502 Card Reader. 

a 50 Magnetic Data Inscriber (of a 

2770). 
a 5496 Data Recorder. 


29 


ID 


29 


ID 




DEVMCODE 


DEVMOD1 
DEVMOD2 


X'OO' 
X'01' 


Device model code: 

Device is designated as Model 1 

Device is designated as Model 2 


30 


IE 


30 


IE 




DEVFLAGS 


DEVCBSC 
DEVCSSL 

DEVCRVB 

DEVCSWL 

DEVCATTN 

DEVCCHEK 
DEVCSTCL 

DEVCSLPN 


X'80' 
X'40' 

X'20' 

X'lO' 

X'08' 

X'04' 
X'02' 

x'or 


The device uses BSC line control 

The device uses start-stop line control, 
but has no Transmit Interrupt feature. 

The device has the Transmit Interrupt 
feature; this means that the applica- 
tion program can interrupt a trans- 
mission from the device by issuing a 
RESET macro instruction. 

The terminal is connected via a 
switched line, rather than a leased 
line. 

The terminal can interrupt the applica- 
tion program (and cause its ATTN 
exit-routine to be scheduled). 

The terminal has the Checking feature. 

The terminal has the Station Control 
feature. 

The terminal has the Selector Pen 
feature. 


31 


IF 


31 


IF 




DEVPHYSA 


- 


- 


Physical device address e.g., 3270 
"from" terminal for COPY operation. 


32 


20 


32 


20 



Figure H-12 (Part 2 of 2). The NIB's DEVCHAR DSECT (ISTDVCHR) 
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PROC DSECT: ISTDPROC 



Field 


DSECT 
DS or ORG 

label 


DSECT 
EQU 
label 


Value 


Meaning (For EQU, meaning 

when bit setting is on or 

when byte value is set) 


DOS/VS 
Displacement 
Dec Hex 


OS/VS 
Displacement 
Dec Hex 


PROC 


PROPROC1 


PROTRUNC 
PROXPOPT 
PRODFASY 
PRORESPX 


X'40' 
X'20' 
X'10' 
XW 


PROC=TRUNC 
=BINARY 
=DFASYX 
=RESPX 


36 


24 


36 


24 




PROPROC2 


PROERPO 
PROLGOT 
PRONTFL 
PROEMLC 
PROCFTX 


X'40' 
X'20' 
X'04' 
X'02' 

x'or 


PROC=NERPOUT 
=NLGOUT 
=NTMFLL 
=ELC 
=CONFTXT 


37 


25 


37 


25 




PROPROC3 


PROERPI 
PROLGIN 
PRONTO 
PROMONIT 


X'40' 
X'20' 
X'10' 
X'04' 


PROC=NERPIN 

=NLGIN 

=NTIMEOUT 

=MONITOR 


38 


26 


38 


26 




PROPROC4 


PROEIB 

PROMODB 

PROMODM 

PROMODT 

PROMODC 


X'80' 
X'08' 
X'04' 
X'02' 

x'or 


PROC=EIB 

=BLOCK 
=MSG 
=TRANS 
=CONT 


39 


27 


39 


27 



Figure H-13. The NIB's PROC DSECT (ISTDPROC) 
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APPENDIX I. DEVICE CONSIDERATIONS 



This appendix lists various device-dependent aspects of programming with VTAM. 
There is a separate section for each supported type of terminal. Much of this 
information can be found elsewhere in this publication; it is repeated here for your 
convenience. 



IBM 1050 Data Communications System 



If FEATURE=ATTN is specified on the TERMINAL macro instruction during 
VTAM definition, the MONITOR processing option should be set in the NIB used 
for connection so that an ATTN exit-routine can be used to handle the attention 
interruptions. 

If FEATURE=TOSUPPR is specified on the TERMINAL macro, the NTIMEOUT 
processing option should be set in the NIB used for connection. 

INQUIRE (OPTCD=DEVCHAR) can be issued to determine the device type in the 
1050 system only if the DEVICE operand is coded for the TERMINAL macro 
instruction during VTAM definition. 

The KEEP processing option should be set if the application program's input area is 
too small to hold the data arriving from the communications controller. (The 
amount of incoming data is affected by the TRANSFER operand of the LINE 
macro and the CUTOFF operand of the GROUP macro. 

Translation from lowercase to uppercase is not provided. 

Idle characters are inserted by the communications controller (as specified with the 
LINESIZ and CRRATE operands of the LINE macro instruction). If the Auto-fill 
character generation feature is present, specify PROC=NTMFLL in the NIB used 
for connection; this will suppress the insertion of idle characters by the 
communications controller. 

If you are using the 1050 in group mode, you will have one symbolic terminal name 
for issuing OPNDST and I/O requests. If you are using the 1050 in specific mode, 
you will have one symbolic terminal name for each component of the system (with 
OPNDST and I/O requests issued for each one). If the installation has provided the 
capability of using the 1050 system in either mode, you should issue OPNDST for 
the component and for the symbolic name representing the entire 1050 system. (If 
more than one component is on the same point-to-point line, you should establish 
connection with only one component at a time.) 

When a 1050 dial-in device exceeds the negative response to polling limit, the NCP 
terminates the input operation and sets the error lock (first bit in FDBK2 set on). 
The error lock can be reset and the input operation retried. If the error persists, 
CLSDST should be issued. 

The MSG, LGIN, LGOUT, BINARY, and EIB processing options are invalid for 
1050 devices. 

For a description of this system, see IBM 1050 Reference Digest, GA24-3020. 



Appendix I: Device Considerations 251 



IBM 2740 Communication Terminal, Model 1 

Translation from lowercase to uppercase is not provided. 

If the terminal has no station control or transmit control feature, data can be 
entered by the terminal operator when the BID key is pressed, even though no 
READ or SOLICIT is pending for the terminal. The communications controller 
ignores the data. To avoid losing the data, verify that the installation has defined 
the terminal as conversational (CONV=YES on the TERMINAL macro) and obtain 
all data with WRITE (OPTCD=CONV) or READ (PROC=CONT) macro instruc- 
tions. 

If you are using the 2740 in group mode, you issue OPNDST and I/O requests for a 
single symbolic terminal name. If you are using the 2740 in specific mode, you 
issue OPNDST and I/O requests for symbolic terminal names representing each 
component of the system that you are addressing in specific mode. If the 
installation has provided you with the capability of using the 2740 in either mode, 
you should issue OPNDST for both the symbolic terminal name representing the 
entire 2740 system, and for the symbolic terminal name of the component. (If 
more than one component is on the same point-to-point line, you should establish 
connection with only one component at a time.) 

The MSG, LGIN, LGOUT, EIB, BINARY, and MONITOR processing options are 
invalid for 2740-1 devices. BLOCK, NERPIN, and NERPOUT are valid only if the 
terminal has the checking feature. 

For a description of the 2740, see IBM 2740 Communication Terminals Models 1 
and 2 Component Description, G A24-3403 . 
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IBM 2740 Communication Terminal, Model 2 



Regardless of the setting of the BLK-LBM-LBT option code when WRITE is issued, 
the output operation is done as though LBT had been set (that is, an EOT is sent to 
the terminal after the terminal receives the block of data and sends a positive 
response). 

If a block of data sent to the terminal is too large to fit in the terminal's buffer, the 
application program is not notified of this fact. 

If a terminal is addressed after a Bid key has been pressed, leading graphic 
characters are returned to the application program indicating that the output 
operation could not be completed normally. If the LGOUT processing option is in 
effect, the leading graphic characters are placed in the WRITE RPL's SENSE field. 

Translation from lowercase to uppercase is not provided. 

If you are using the 2740 in group mode, issue OPNDST and I/O requests for a 
single symbolic terminal name. If you are using the 2740 in specific mode, issue 
OPNDST and I/O requests for the symbolic terminal names representing each 
component of the system that you are addressing in specific mode. If the 
installation has provided the capability of using the 2740 in either mode, you 
should issue OPNDST for both the symbolic terminal name representing the entire 
2740 system, and for the symbolic terminal name of the component. (If more than 
one component is on the same point-to-point line, you should establish connection 
with only one component at a time.) 

The MSG, NTMFLL, EIB, NTIMEOUT, MONITOR, ELC, and BINARY processing 
options are invalid for 2740-2 devices. BLOCK is valid only if the terminal has the 
checking feature. 

For a description of the 2740, see IBM 2740 Communication Terminals Models 1 
and 2 Component Description, GA24-3403. 
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IBM 2741 Communication Terminal 



If FEATURE=ATTN is specified on the TERMINAL macro during VTAM 
definition, the MONITOR processing option should be set in the NIB used for 
connection so that an ATTN exit-routine can be used to handle the attention 
interruptions. 

No text timeout limitation is provided for the terminal (that is, once EOA has been 
sent from the terminal, no time limit between successive data characters exists). 
The NTIMEOUT processing option should be specified. 

SOLICIT (PROC=CONT) causes an EOA and an EOT to be sent to the terminal, 
placing it in a transmit state. Before issuing WRITE while soliciting data with CONT 
set, RESET (OPTCD=COND) must be issued. 

Conversational output (WRITE with OPTCD=CONV) is valid for 2741 terminals, 
even though the terminal cannot be specified during VTAM definition as 
conversational. 

If the terminal has no break feature, the first I/O request following connection 
should be READ or SOLICIT. The READ or SOLICIT may be completed in error if 
the terminal was powered on before the communications controller became active; 
if this occurs, issue RESET followed by WRITE to maintain the conversational 
mode of the 2741 terminal. 

The LGIN, LGOUT, EIB, NERPIN, NERPOUT, and BINARY processing options 
are invalid for a 2741 terminal. 

For a description of the 2741, see IBM 2741 Communication Terminal, 
GA24-3415. 
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IBM Communicating Magnetic Card Selectric Typewriter 



If FEATURE=ATTN is specified on the TERMINAL macro during VTAM 
definition, the MONITOR processing option should be set so that an ATTN 
exit-routine can be used to handle the attention interruptions. 

If the terminal has no break feature, the first I/O request following connection 
should be READ or SOLICIT. The READ or SOLICIT may be completed in error if 
the terminal was powered on before the communications controller became active; 
if this occurs, issue RESET followed by WRITE to maintain the conversational 
mode of the terminal. 

Text timeouts can be suppressed with the NTIMOUT processing option. 

The LGIN, LGOUT, EIB, and BINARY processing options are invalid for this 
terminal. 
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IBM World Trade Telegraph Station (WTTY) 



If FEATURE=ATTN is specified on the TERMINAL macro during VTAM 
definition, an ATTN exit-routine can be used to handle the attention interruptions. 
The MONITOR processing option must be set in order for the ATTN exit-routine 
to be scheduled. 

If the MSG processing option is used for solicitation, the end-of-block sequence 
must be defined by the installation (with the GROUP macro). If TRANS is used, 
the end-of-transmission sequence must be defined by the installation (GROUP 
macro). CONT (continuous solicitation) can be used, but should be avoided if 
output for the terminal occurs frequently. If CONT is used, RESET must be issued 
before WRITE can be issued. 

No terminal ID verification is provided. 

Conversational writing (WRITE with OPTCD=COND) is valid for this terminal. 

Text timeouts can be suppressed by setting the NTIMEOUT processing option for 
the terminal. 

The LGIN, LGOUT, NTMFLL, EIB, NERPIN, NERPOUT, and BINARY processing 
options are invalid for this terminal. 
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IBM System/ 7 CPU 



The System/7 is supported as a 2740 (Model 1 with checking) on a switched or 
nonswitched point-to-point start-stop line or as a System/3 on a BSC line. 

The BLOCK, MSG, LGIN, LGOUT, NTMFLL, EIB, NERPIN, NERPOUT, 
MONITOR, and BINARY processing options are invalid for the System/7. 

A remote IPL of the System/7 is implemented by issuing a series of WRITE macro 
instructions to send the IPL object program text to the device. The ELC-NELC 
processing option must be set to ELC, and idle characters must not be used. Format 
the output data like this: 

E E U D L E 

First WRITE: C E C object program text 

T A L B 

E E 

Successive WRITEs : object program text 

A B 

E E 

Last WRITE: object program text 

A T 

(The EOT in the first WRITE is used to place the System/7 in stand-by mode in 
case it is not prepared to receive data.) 
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AT&T 83B3 Selective Calling Station 

Conversational output (WRITE with OPTCD=CONV) is valid for this terminal. 

Solicitation with BLOCK or MSG is handled by VTAM as though TRANS had been 
specified. If the CONT processing option is used, all WRITE requests must be 
preceded by RESET. Avoid CONT if WRITE requests are to be issued frequently. 

If you are using the terminal in group mode, issue OPNDST and I/O requests to the 
symbolic terminal name representing the terminal. If you are using the terminal in 
specific mode, issue OPNDST and I/O requests to the various symbolic terminal 
names assigned to each component of the terminal. If the installation has provided 
the capability for using the terminal in either mode, you should issue OPNDST for 
the symbolic terminal name that represents the terminal, and for the symbolic 
terminal name that represents the terminal component. (If more than one 
component is on the same point-to-point line, you should establish connection with 
only one component at a time.) 

The LGIN, LGOUT, NTMFLL, EIB, NTIMEOUT, NERPIN, NERPOUT, 
MONITOR, and BINARY processing options are invalid for this device. 
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AT&T Teletypewriter Terminal, Models 33 and 35 (TWX) 



If FEATURE=ATTN is specified on the TERMINAL macro during VTAM 
definition, an ATTN exit-routine can be used to handle the attention interruptions. 
The MONITOR processing option must be set if the ATTN exit-routine is to be 
scheduled. 

Text timeouts can be suppressed by setting the NTIMEOUT processing option. 

Solicitation with BLOCK or MSG is handled as though TRANS had been specified. 
If the CONT processing option is used, all WRITE requests must be preceded by 
RESET. Avoid CONT if WRITE requests are to be issued frequently. 

Conversational output (WRITE with OPTCD=CONV) is valid for this terminal. 

The LGIN, LGOUT, EIB, NERPIN, NERPOUT, and BINARY processing options 
are invalid for this device. 
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WESTERN UNION PLAN 115 A Station 



Solicitation with BLOCK or MSG is handled by VTAM as though TRANS had been 
specified. If the CONT processing option is used, all WRITE requests must be 
preceded by RESET. Avoid CONT if WRITEs are to be issued frequently. 

Conversational output (WRITE with OPTCD=CONV) is valid for this terminal. 

If you are using the terminal in group mode, issue OPNDST and I/O requests to the 
symbolic terminal name representing the terminal. If you are using the terminal in 
specific mode, issue OPNDST and I/O requests for the symbolic terminal names 
representing each terminal component with which you wish to communicate. If the 
installation has provided the capability of using the terminal in either mode, you 
should issue OPNDST for both the symbolic terminal name that represents the 
terminal, and for the symbolic terminal name that represents the terminal 
component. (If more than one component is on the same point-to-point line, you 
should establish connection with only one component at a time.) 

The LGIN, LGOUT, NTMFLL. EIB, NTIMEOUT, NERPIN, NERPOUT, 
MONITOR, and BINARY processing options are invalid for this device. 



260 



IBM 2770 Data Communication System 



By setting the ERASE-EAU-NERASE option code to ERASE, a WRITE macro 
instruction causes a ERASE/WRITE command to be sent to the system's 2265 
terminal. ERASELBM or ERASELBT LDOs can also be used. 

To send a WRITE at Line Address command to a 2265 terminal, include the WLA 
escape sequence in the data stream that is to be written to the terminal. 

Error recovery messages from the 2770 system in the form of 



s 






s 




E 





% 


s 


T 


text 


T 


H 






X 




X 



S 




E 


T 
X 


text 


X 
X 



are not recognized as such by VTAM or the communications controller, but are 
handled by VTAM as a text message with header. The communications controller 
removes the imbedded STX and passes the remainder to the application program as 
two blocks: 

First block: % S Second block: text 

When the application program receives the first block, bit 7 (DATAFLG=SOH) is 
set on, indicating header data. Another READ is required to receive the second 
block. 

Test Request Messages (which begin SOH % /) are intercepted by the communi- 
cations controller and supplied to the Teleprocessing On-line Test Executive 
Program (TOLTEP) by VTAM. The READ macro instruction that would have 
moved the message into program storage had the interception not occurred is 
canceled with RTNCD=12 and FDBK2=2. 

Request for Test messages of the form 

S 

% XYN addr 

H 

are not intercepted, but are passed on to the application program in the same 
manner that any text message with header data would be passed: the application 
program's READ obtains the header portion, with the SOH removed and with bit 7 
(DATAFLG=SOH) set on in the RPL's FDBK field; a second READ is required for 
the text portion. 

Data may be sent in transparent text mode to the 2770 by specifying 
PROC=BINARY in the NIB used for connection. Before sending the transparent 
text blocks on a point-to-point line, the communications controller first obtains the 
component selection character and inserts it into a block which it sends in 
nontransparent text mode. (The component selection character is supplied by the 
installation in the ADDR operand of the COMP macro instruction.) 

Data sent from the device in transparent text mode is placed in the application 
program's input area unaltered. The application program can check the NCP return 
codes in the extended response byte of the SENSE field to determine whether the 
data was sent in transparent text mode. 

VTAM does not compress output data or expand input data; this must be done by 
the application program. 
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The LGIN, LGOUT, NTMFLL, NTIMEOUT, and MONITOR processing options are 
invalid for the 2770. 

For a description of the 2770, see System Components: IBM 2770 Data 
Communication System, GA2 7-3013. 
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IBM 2780 Data Transmission Terminal 



s 




E 


T 
X 


text 


X 
X 



Device-control characters required for Vertical Forms Control must be supplied by 
the application program. The application program must likewise supply the control 
characters for Printer Horizontal Format Control (including the escape sequence 
ESC HT ...). 

Test Request Messages (which begin SOH % /) are intercepted by the communi- 
cations controller and supplied to the Teleprocessing On-line Test Executive 
Program (TOLTEP) by VTAM. The READ macro instruciton that would have 
moved the message into program storage had the interception not occurred is 
canceled with RTNCD=12 and FDBK2=2. 

Request for Test messages of the form 

S 

% XYN addr 

H 

are not intercepted, but are passed on to the application program in the same 
manner that any text message with header data would be passed: the application 
program's READ obtains the header portion, with the SOH removed and with bit 7 
(DATAFLG=SOH) set on in the RPL's FDBK field; a second READ is required for 
the text portion. 

Data may be sent in transparent text mode by specifying PROC=BINARY for the 
NIB used for connection. Before sending the transparent text blocks on a 
point-to-point line, the communications controller first obtains the component 
selection character and inserts it into a block which it sends in nontransparent text 
mode. (The component selection character is supplied by the installation in the 
ADDR operand of the COMP macro instruction.) 

Data sent from the device in transparent text mode is placed in the application 
program's input area unaltered. The application program can check the NCP return 
codes in the extended response byte of the SENSE field to determine whether the 
data was sent in transparent text mode. 

The LGIN, LGOUT, NTMFLL, NTIMEOUT, and MONITOR processing options are 
invalid for 2780 devices. 

For a description of the 2780, see Component Description: IBM 2780 Data 
Transmission Terminal, GA27-3005. 
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IBM 2972 General Banking Terminal System (Models 8 and 11) 

Request for Test message of the form 

S 

% XYN addr 

H 



s 




E 


T 


text 


X 


X 




X 



are not intercepted by the communications controller and passed to the 
Teleprocessing On-line Test Executive Program (TOLTEP). Instead, VTAM passes 
the message to the application program in the same manner that any text message 
with header data is passed: the application program's READ obtains the header 
portion, with the SOH removed and with bit 7 (DATAFLG=SOH) set on in the 
RPL's FDBK field; a second READ is required for the text portion. 

The Batched Message feature is not supported by VTAM. 

VTAM removes the 1-byte station address from the input data before moving the 
data into the application program's input area. 

If a 2980 (Model 1 or 4) Teller Station includes a passbook printer or a 2980 
(Model 2) Administrative Station includes an auditor key, VTAM assigns a symbolic 
name to the passbook printer or auditor key. VTAM forms the name by prefixing a 
dollar sign ($) to the name of the 2980's TERMINAL entry and deleting the last 
character of the name. When the application program issues INQUIRE 
(OPTCD=TERMS) using the 2980's TERMINAL entry name, VTAM places the 
passbook printer or auditor key name in the NIB generated by INQUIRE. 

The BLOCK, MSG, LGIN, LGOUT, NTMFLL, NTIMEOUT, and MONITOR 

processing options are invalid for 2972 devices. 

For a description of the 2972 system, see Component Description: IBM 2972 
Models 8 and 11 General Banking Terminal Systems, GL27-3020. 
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IBM 3270 Information Display System (Record-mode) 



The application program can communicate with a 3270 as a BSC or locally attached 
terminal or as though it were a logical unit. The terminal is treated as a logical unit 
by setting the NIB's MODE field to RECORD when the terminal is connected, and 
by exchanging messages and responses with SEND and RECEIVE macro instruc- 
tions. None of the basic-mode macro instructions can be used. 

Different devices on the same control unit may be used in different modes at the 
same time. A 3270 can be disconnected in one mode and reconnected in another. 

Since the 3270 is not a logical unit and has no programmable capabilities, VTAM 
cannot make a 3270 appear exactly like a logical unit to the application program. 
Consequently, restrictions apply to all SEND, RECEIVE, and SESSIONC communi- 
cation with the 3270 terminal. These restrictions are described below. All aspects of 
communication (and connection) not mentioned apply as though the 3270 were a 
logical unit. 

All commands and orders for the 3270 must be placed in the output data by the 
application program. 

A SEND macro instruction may point to a data area containing a Read Modified 
command to be sent to the device. The data retrieved from the device is placed in 
the application program's storage area in this format: 

AID CUR 1 CUR 2 device control characters, orders, text 

where AID is the Attention Identification and CUR 1 and CUR 2 form the two-byte 
cursor address. If the terminal operator causes a "short read" to occur at the 
terminal (by pressing the CLEAR key or a Program Access key, for example), the 
input data consists of the AID only. 

When a Copy command is placed in the data stream, the application program must 
include the physical device address of the "from" device. This address can be 
obtained by issuing INQUIRE (OPTCD=DEVCHAR). See Appendix H for the 
location of the physical device address in DEVCHAR. Note that a Copy operation 
is not valid for a locally attached 3270 terminal. 

No responses should be sent to the 3270. All incoming messages indicate that no 
response of any type is expected. 

Messages sent to the 3270 should contain only data. No quiesce, change-direction, 
bid, chase, or cancel indicators should be sent. If the application program attempts 
to send one of these indicators, the SEND is completed with RTNCD=20 and 
FDBK2=71. Bracket indicators are used as described below. Chaining indicators 
should always mark the message as the sole element of a chain— that is, 
CHAIN=ONLY (all incoming messages are so marked). 

No SESSIONC indicators can be received from the 3270 terminal. Only the clear 
indicator can be sent to it. The effect of the clear indicator is to reset both 
incoming and outgoing sequence numbers to 0. 

The brackets convention must be used. If the application program has no use for 
brackets, the entire interval between the first I/O request (following connection) 
and disconnection can be considered to be one bracket. Both the application 
program and the 3270 can begin a bracket. 
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The first input from a 3270 that begins an NCP session is marked as the beginning 
of a bracket. All subsequent messages received from the 3270 during the NCP 
session indicate that the bracket is being continued. The 3270 cannot end a 
bracket; this can only be done by the application program. The application program 
can begin and end a bracket with the same message— that is, BRACKET=(BB,EB) 
can be specified for the SEND RPL. 

If both the application program and the 3270 attempt to begin a bracket at the 
same time, the response to the application program's SEND indicates Request 
Reject (SSENSEI=RR). If the application program attempts to begin a new bracket 
without ending the current one, a STATE error (SSENSEI=STATE) is returned. 

When the SEND data stream contains a Read command, the resulting input is 
received as a separate message, not as a response to the SEND operation. The 
application program should not begin or end a bracket when the data being sent 
contains a Read command. The application program must request normal and 
exception FME responses for each message sent to the 3270 that begins or ends a 
bracket. Normal and exeption FME responses are requested by setting 
RESPOND=(NEX,FME,NRRN) for the SEND RPL. FME responses should also be 
requested when a message is sent to a printer. All other output can indicate that 
either exception responses only— RESPOND=(EX,FME,NRRN)— or normal or 
exception responses-RESPOND=(NEX,FME,NRRN)-are expected. RRN 
responses are not used. 

Status and sense information is available in the RPL's USENSEI field when an 
exception response is received or when a logical-unit-status (LUS) indicator is 
received. The format of the information is the same as the 2-byte combined sense 
and status (S/S) format returned from a BSC 3270 except that the 2 high-order bits 
of each byte are set to 0. 

The SSENSEI (system sense) field is set following the receipt of exception 
responses, but the SSENSMI (system sense modifier) field is always set to 0. The 
SSENSEI field can be set to indicate a PATH error (SSENSEI=PATH), a STATE 
error (SSENSEI=STATE) a Request Reject error (SSENSEI=RR) or no error 
(SSENSEI=0). See the description of the SSENSEI field near the end of Appendix 
C. 

Logon requests for the 3270 cannot originate from the 3270 terminal itself (unlike 
a logical unit) except via the network solicitor. 

Test Request Messages from locally attached terminals are intercepted by VTAM 
and supplied to the Teleprocessing On-line Test Executive Program (TOLTEP). Test 
Request Messages from remotely attached terminals are intercepted by the 
communications controller and also supplied to TOLTEP by VTAM. The arrival of 
the Test Request Message causes the RECEIVE macro instruction to be completed 
with an error return code. A clear operation is performed (as though the application 
program had sent a clear indicator) and all pending communication is cancelled. 
The application program should disconnect the terminal. Connection is established 
in the same manner as it was initially-either by the ACQUIRE or by the ACCEPT 
formofOPNDST. 

For a description of the 3270 system, see IBM 3270 Information Display System 
Component Description, G All '-2749. 
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IBM 3270 Information Display System (Basic-mode) 

The application program can communicate with a 3270 as a BSC terminal or as 
though it were a logical unit. The terminal is handled as a BSC or locally attached 
terminal by setting the NIB's MODE field to BASIC when the terminal is 
connected, and by exchanging data with READ and WRITE macro instructions. 
None of the record-mode macro instructions can then be used. Different devices on 
the same control unit may be used in different modes at the same time. A 3270 
device can be disconnected and reconnected in the other mode. 

When the terminal sends sense and status information in response to a READ, 
WRITE, or DO macro instruction, VTAM places the information in the RPL's 
SENSE field. VTAM also sets the RPL's RTNCD field to 4 and sets the FDBK2 
field to 2 to signal that the SENSE field has been set. The SENSE field codes are 
described below. 

If the SENSE field indicates that an error arose because operator intervention was 
required at the device, the failed operation may be retried after execution of a 
RESET macro instruction with OPTCD set to UNCOND or LOCK. 

To unlock the keyboard of a 3270 display station, issue a WRITE macro instruction 
with an unlock-key board control character included in the data stream. 

Test Request Messages (which begin SOH % /) from locally attached terminals are 
intercepted by VTAM and supplied to the Teleprocessing On-line Test Executive 
Program (TOLTEP). Test Request Messages from remotely attached terminals are 
intercepted by the communications controller and also supplied to TOLTEP by 
VTAM. 

The BLOCK, MSG, CONT, LGIN, LGOUT, NTMFLL, EIB, NTIMEOUT, ELC, and 
MONITOR processing options are invalid for 3270 devices. BINARY is invalid for 
locally attached devices. 

The BLK-LBM-LBT option code (applicable for output) should be set to LBT; BLK 
is invalid, and LBM requires that you be aware of whether the device is locally or 
remotely attached (because no line control characters are sent regardless of the 
attachment mode— see Appendix B). 

Input Considerations Since VTAM deletes all line-control characters arriving from remotely attached 

devices, your input processing need not take into account whether the device is 
locally or remotely attached. 

To avoid losing incoming data when the input area is too small, specify the KEEP 
processing option in the NIB used to connect the device. Then if the data is too 
long to fit, VTAM will fill the input area to capacity, set the second bit 
(DATAFLG=EOB) of the FDBK field off, and hold the remaining data for the next 
read request. See the KEEP-TRUNC processing in the NIB macro instruciton for 
further details. 

A READBUF LDO can be used to send a Read Buffer command to a terminal. See 
the LDO macro instruction (CMD=READBUF) for an explanation of how this is 
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Output Considerations 



Copy Considerations 



accomplished. The data in the application program's input area upon completion of 
the DO macro instruction is arranged like this: 

CUR 1 CUR 2 



AID 



SF 



ATTR 



text 



where AID is the Attention Identification and CUR 1 and CUR 2 form the 2-byte 
cursor address. The SF (Start Field) and ATTR (Attribute Byte) are present only if 
the device buffer is formatted. 

There are three different output operations available; they are selected by setting 
the ERASE-EAU-NERASE option code in the RPL of a WRITE macro instruction. 

WRITE (OPTCD=ERASE) is a two-part operation; it first clears the device's entire 
buffer, and then it sends the output data that you provide via the RPL's AREA 
field. In the beginning of that data you must provide the Write Control Character 
(WCC) followed by the appropriate device control characters, orders, and text. If 
you set the BLK-LBM-LBT option code to LBT, you need not include line control 
characters; VTAM will include them for remotely attached devices, and omit them 
for locally attached devices. 

WRITE (OPTCD=EAU) sends an Erase All Unprotected command to the device. 
Since no output data is involved with this form of WRITE, set the RPL's RECLEN 
field to 0. 

WRITE (OPTCD=NERASE) sends a Write command to the device. You must 
prepare the output data in exactly the same manner as is specified above for 
OPTCD=ERASE: begin the output data with WCC, followed by the appropriate 
device-control characters and orders. 

With the COPYLBM LDO, an application program can send a "copy" command to 
copy the contents of a remotely attached 3277 Display Station to any other display 
station or printer connected to the same control unit. The COPYLBT LDO works 
like COPYLBM, except that after the data has been copied, VTAM waits for the 
"to" device's response and sends an EOT when the response is detected. 

Note: Since this facility is available only for remotely attached devices, you may 
wish to simulate a copy operation with READ and WRITE macro instructions. 
Using READ and WRITE macros allows you to use the same program code to 
handle copy operations for both locally and remotely attached devices. 

Specific information about using these LDOs is given in the DO and LDO macro 
instruciton descriptions. Briefly, the procedure is this: The LDO is built and its 
ADDR field set to point to a 3-byte area containing (1) a copy control character, 
and (2) the second 2 bytes of the "from" device's CID (in that order). A COPYLBT 
LDO must be used if the Start Print bit (bit 4) in the copy control character is set 
on. The LDO's LEN field must be set to 3. The address of the LDO is placed in the 
RPL's AREA field and the CID of the "to" device is placed in the ARG field. The 
RPL's ACB field must indicate the same ACB that was indicated by the RPL used 
to connect the "from" and "to" devices. 

Note: The operation will not work if the "from" device's buffer is locked against a 
copy operation. An application program can lock a "from" device's buffer by 
placing an attribute of Protected /Alphameric (hexadecimal 60) in buffer location 0, 
and setting the byte at buffer location 1 to zeros. 
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Sense Information When a READ, WRITE, or DO macro instruction is completed, the SENSE field 

may contain 2 bytes of status and sense information. If the SENSE field is 
extracted with SHOWCB, the 2 bytes are right-adjusted in the fullword work area. 
The possible hexadecimal values of the 2 bytes are: 

Meaning 

Data check or bus-out check 

Intervention required 

Command rejected 

Operation check 

Control check 

Data check with unit specify 1 

Equipment check 2 

Data check, unit specify, and device end 1 

Intervention required and device end 1 

Equipment check, unit specify, device end, and 

intervention required 1 

Equipment check, unit specify, and device end 

Data check and device end 

Operation check and device end 

Control check and device end 

For locally attached devices, attention status may also accompany this condition. 
For locally attached devices, attention status always accompanies this condition. 

Note that unit check occurs in the status of locally attached devices for all of the 
above conditions. 

For a description of the 3270 system, see IBM 3270 Information Display System 
Component Description, GA27-2749. 
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IBM 3600 Finance Communication System 



The application program establishes connection with a 3600 terminal (that is, the 
application program in the controller) in the same manner as with a BSC or 
start-stop terminal. A logon request, however, can originate from the terminal itself 
(Initiate Self). The 3601 controller contains one or more logical units, and 
record-mode macro instructions are used to communicate with them. The unique 
aspects of communication with a 3600 terminal are described in the SEND, 
RECEIVE, RESETSR, and SESSIONC macro instructions. For a general descrip- 
tion of the 3600 system, see IBM 3600 System Summary, GC27-0001 . 
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IBM 3735 Programmable Buffered Terminal 

Data to be sent to the 3735 should be formatted in this manner: 
Form Description Program message: 

Preliminary message: 
Data block: 



N 




N 


U 


F 


U 


L 




L 



Unpacked FDP data block 



Ending message: 



Selectric message: 



Terminate Communication Mode: 



Inquiry: 



Power down: 



CPU ID list: 



Each entry in the ID list contains the CPU ID of all CPUs that may 
communicate with the 3735 over switched lines. The CPU ID is defined by 
the installation in the CUID operand of the BUILD macro instruction. 

Status messages reporting abort conditions are sent from the terminal as 

S N N E 

T US U S 1 S 2 T 
X L L X 

but when the block is placed in the application program's input area, the 
line-control characters are deleted: 



S 1 



When sending Form Description Program (FDP) data blocks to the terminal in 
ASCII transmission code, the last 6 bytes of the block must each be changed from 
FF to 7F or else deleted entirely. To remove your dependency on the transmission 
code used, it is recommended that you always remove the last 6 bytes (the sector 
flags) from FDP data blocks. You can accomplish this by specifying RECLEN=470 
instead of RECLEN=476 in the RPL used for WRITE. 
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ID list 
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A READ macro instruction must be the first I/O request issued for a 3735 terminal 
following connection. All other requests will be rejected until a READ is issued. 

The NTMFLL, NTIMEOUT, and MONITOR processing options are invalid for the 
3735 terminal. 

For a description of the 3735 terminal, see IBM 3735 Programmer's Guide, 
GC30-3001. 
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IBM 3740 Data Entry System 



When the 3740 system sends sense data in response to READ, WRITE, or DO 
macro instructions, VTAM places the sense data in the RPL's SENSE field. 

Request for Test messages of the form 

S S E 

% XYN addr T text T 
H XX 

are not intercepted and passed to the Teleprocessing On-line Test Executive 
Program (TOLTEP) by VTAM, but are passed to the application program in the 
same manner as any text message with header data: the application program's 
READ obtains the header portion, with the SOH removed and with bit 7 
(DATAFLG=SOH) set on in the RPL's FDBK field; a second READ is required for 
the text portion. 

Data may be sent to the terminal in transparent text mode by specifying 
PROC=BINARY for the NIB used to connect the terminal. Data sent from the 
terminal in transparent text mode is placed in the application program's input area 
unaltered. The application program can determine that the data was sent in 
transparent text mode by examining the NCP return code in the extended response 
byte of the SENSE field. 

The LGIN, LGOUT, NTMFLL, NTIMEOUT, and MONITOR processing options are 
invalid for 3740 devices. 

For a description of the 3740 system, see IBM 3740 Data Entry System Reference 
Manual, GA21-9151. 
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IBM 3780 Data Transmission Terminal 



Data may be sent to the 3780 in transparent text mode by specifying 
PROC=BINARY for the NIB used to connect the terminal. Before sending the 
transparent text blocks on a point-to-point line, the communications controller first 
obtains the component selection character and inserts it into a block which it sends 
in nontransparent text mode. The component selection character is supplied by the 
installation in the ADDR operand of the COMP macro instruction. 

Data sent from the device in transparent text mode is placed in the application 
program's input area unaltered. The application program can determine that the 
data was sent in transparent text mode by examining the NCP return code in the 
extended response byte of the SENSE field. 

The application program must supply the control sequences required for Horizontal 
Format Control and Vertical Forms Control. 

VTAM does not compress output data or expand input data. 

Test Request Messages (which begin SOH % /) are intercepted by the communi- 
cations controller and supplied to the Teleprocessing On-line Test Executive 
Program (TOLTEP) by VTAM. The READ macro instruction that would have 
moved the message into program storage had the interception not occurred is 
canceled with RTNCD=12 and FDBK2=2. 

Request for Test messages of the form 

S S E 

% XYN addr T text T 
H XX 

are not intercepted, but are passed on to the application program in the same 
manner that any text message with header data is passed: the application program's 
READ obtains the header portion, with the SOH removed and with bit 7 
(DATAFLG=SOH) set on in the RPL's FDBK field; a second READ is required for 
the text portion. 

Error recovery messages of the form 

S S E 

% S T text T 
H XX 

are likewise passed on to the application program as two blocks— the first is the 
header portion with the SOH removed, the second is the text portion, with the STX 
and ETX removed. 

The LGIN, LGOUT, NTMFLL, NTIMEOUT, and MONITOR processing options are 
invalid for 3780 devices. 

For a description of the 3780, see Component Information for the IBM 3780 Data 
Communication Terminal, GA27-3063. 
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IBM System/ 3 CPU 



The System/3 is supported as a BSC station on switched lines, and on both 
point-to-point and multipoint nonswitched lines. The EBCDIC and ASCII trans- 
mission codes are supported. 

Data blocks received from the System/3 that contain both header data and text are 
handled as two blocks: the application program's READ obtains the header 
portion, with the SOH removed and with bit 7 (DATAFLG=SOH) set on in the 
RPL's FDBK field; a second READ is required for the text portion. 

When the System/3's Continuous Conversation function is active, the CPU engages 
in a continuous exchange of write operations and conversational replies. To 
communicate with the System/3 in this manner, you must: 

1 . Specify PROC=MSG for the NIB used to connect the application program to the 
System/3 CPU 

2. Specify OPTCD=CONV for all WRITE macro instructions 

3. Issue WRITE with RECLEN=0 if no data is ready to be sent to the System/3 
CPU 

4. Be prepared to receive a reply of zero length 

The READ, WRITE, WRITELBM, WRITELBT, WRTHDR, WRTPRLG, and 
WRTNRLG LDOs can be used with the System/3. See the description of the LDO 
macro instruction. 

If leading graphic characters are received as a response to a WRITE macro 
instruction, the FDBK field is set to indicate this (DATAFLG=LG). The next 
READ macro instruction directed at the device will obtain the leading graphic 
characters. If leading graphic characters are received in response to a conversational 
WRITE (OPTCD=CONV), the leading graphic characters are placed in the data area 
indicated by the AAREA field of the RPL. 

The NTMFLL and MONITOR processing options cannot be used with the 
System/3. 
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IBM System/ 370 CPU 



The System/370 is supported on switched or nonswitched point-to-point BSC lines. 
The EBCDIC and ASCII transmission codes are supported. 

Data blocks received from the System/370 that contain both header data and text 
are handled as two blocks: the application program's READ obtains the header 
portion, with the SOH removed and with bit 7 (DATAFLG=SOH) set on in the 
RPL's FDBK field; a second read is required for the text portion. 

The READ, WRITE, WRITELBM, WRITELBT, WRTHDR, WRTPRLG, and 
WRTNRLG LDOs can be used with the System/370. See the description of the 
LDO macro instruction. 

If leading graphic characters are received as a response to a WRITE macro 
instruction, the FDBK field is set to indicate this (DATAFLG=LG). The next 
READ macro instruction directed at the device will obtain the leading graphic 
characters. If leading graphic characters are received in response to a conversational 
WRITE (OPTCD=CONV), the leading graphic characters are placed in the data area 
indicated by the AAREA field of the RPL. 

The NTMFLL and MONITOR processing options cannot be used with the 
System/370. 
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GLOSSARY 



If you cannot find a term, first check the index, and then 
consult the Data Processing Glossary, GC20-1699. 



ACB: Access method control block. 

acceptance: The process of connecting a node in response to a 
logon request from that node. A node is "accepted" with an 
OPNDST macro instruction having the ACCEPT option code set 
in its RPL. 

access method control block: In VTAM, a control block that 
links an application program to VTAM. Abbreviated ACB. 

acquisition: The process of initiating and securing connection to 
another node. A node is "acquired" with an OPNDST macro 
instruction having the ACQUIRE option code set in its RPL or 
with a SIMLOGON macro followed by OPNDST (ACCEPT). 

any-mode: (1) The form of READ or RECEIVE operation that 
obtains data from any single terminal, (2) the form of SOLICIT 
operation that solicits data from all eligible connected terminals, 
or (3) the form of OPNDST operation that establishes connec- 
tion with any single eligible terminal from which a logon request 
has been received. The any-mode is established by specifying 
OPTCD=ANY for the RPL used by the READ, RECEIVE, 
SOLICIT, or OPNDST macro instruction. 

application program: The request and control blocks that refer 
to a given ACB, or are pointed to by that ACB. 

application program identification: In VTAM, the symbolic 
name by which a teleprocessing program is identified to VTAM 
and the rest of the teleprocessing network. This name is pointed 
to by the ACB's APPLID field. 

asynchronous flow messages: Messages that are received ahead 
of any synchronous flow messages that may be queued for the 
application program or terminal. 

For example: If an application program were to issue a 
RECEIVE macro instruction indicating that either synchronous 
or asynchronous flow messages could satisfy the macro instruc- 
tion, VTAM would not satisfy the RECEIVE macro with 
synchronous flow messages until it had determined that no 
asynchronous flow messages were available. 

asynchronous request: A request that causes control to be 
returned to the application program as soon as possible after the 
request has been accepted by VTAM. When the operation is 
completed, VTAM either invokes the RPL exit-routine, or posts 
an ECB. A request is made asynchronous by setting the ASY 
option code in its RPL. Contrast with synchronous request. 

automatic logon request: A logon request to a specified applic- 
ation program, generated by VTAM (rather than by the terminal 
itself) when the terminal becomes available for connection and 
the application program has opened its ACB and issued 
SETLOGON (OPTCD=START). Automatic logon requests are 
specified by the installation during VTAM definition. 

B 

basic-mode: A set of facilities (including the macro instructions 
needed to use them) that enable the application program to 
communicate with BSC and start-stop terminals, including the 
locally attached 3270 Information Display System. READ, 
WRITE, SOLICIT, RESET, DO, and LDO macro instructions are 
basic-mode macro instructions. 



bid indicator: An indicator used to determine if a new bracket 
can be started. The node receiving the bid indicator sends a 
normal response if a new bracket can be started or sends an 
exception response if a new bracket cannot be started. A bid 
indicator is sent when a SEND macro instruction is issued with 
CONTROL=BID set in its RPL. 

block: In VTAM, the smallest unit of data that may be 
transmitted between an application program and a terminal 
connected in basic-mode. The maximum size of a block is 
determined by the characteristics of the device that is sending or 
receiving the data. For start-stop devices, a block is a unit of data 
beginning with an EOA or EOB character, and ending with an 
EOT or EOB character; for BSC devices, a block is a unit of data 
between an STX or SOH character and an ETB or ETX 
character. Contrast with message and transmission. 

bracket: An exchange of data between an application program 
and a logical unit which accomplishes some task. 

bracket communication: A method of communication in which 
a node does not begin a new bracket until the current bracket 
has been completed. 

BSC: Binary synchronous communications. 



CA mode: See continue-any mode. 

cancel indicator: An indicator that signifies to its receiver that 
the current chain being received should be discarded. A cancel 
indicator is sent when a SEND macro instruction is issued with 
CONTROL=CANCEL set in its RPL. 

change-direction-command indicator: An indicator sent by one 
node to another indicating that the sending node has finished 
transmitting and is prepared to receive. 

change-direction communication: A method of communication 
in which the transmitting node ceases transmitting on its own 
initiative, signals this fact to the other node, and prepares to 
receive. 

change-direction-request indicator: An indicator sent by one 
node to another requesting that a change-direction-command 
indicator be returned. 

chase indicator: An indicator that when returned to its origi- 
nator, signifies all responses have transmitted. A chase indicator 
is sent by issuing a SEND macro instruction with CONTROL= 
CHASE set in its RPL. 

CID: Communications Identifier. 

closedown: The process of deactivating VTAM and the telecom- 
munication network. See also quick closedown and orderly 
closedown. 

cluster control unit: A device that can control the input/output 
operations of more than one device. A remote cluster control 
unit can be attached to a host CPU only via a communications 
controller. A cluster control unit may be controlled by a 
program stored and executed in the unit; for example, the IBM 
3601 Finance Communications Controller. Or it may be control- 
led entirely by hardware; for example, the IBM 2972 Station 
Control Unit. See also communications controller, 
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communications controller: A type of communication control 
unit whose operations are controlled by a program stored and 
executed in the unit. 

Communications Identifier: A VTAM-assigned network-oriented 
equivalent for a terminal's symbolic name. The installation 
assigns a symbolic name to each terminal (or dial-up line) in its 
network configuration. When the application program requests 
connection to the terminal-by placing the terminal's symbolic 
name into a NIB and issuing an OPNDST macro instruction- 
VTAM converts this eight-byte symbolic name into a four-byte 
identifier. The application program must use this identifier for 
all subsequent communication with the terminal. Abbreviated 
CID. 

connection: In VTAM, in response to a request from an 
application program (OPNDST), the linking of VTAM control 
blocks in such a way that the program can communicate with a 
particular terminal. The connection process includes establishing 
and preparing the network path between the program and the 
terminal. Contrast with queued for logon. 

continue-any (CA) mode: A state into which a terminal is 
placed that allows its input to satisfy an input request issued in 
the any-mode. While this state exists, input from the terminal 
can also satisfy input requests issued in the specific-mode. 
(Contrast with continue-specific mode, where input from the 
terminal can satisfy only input requests issued in the 
specific-mode.) Continue-any mode is established by specifying 
OPTCD=CA for the RPL used by an OPNDST or any I/O macro 
instruction. 

continue-specific (CS) mode: A state into which a terminal is 
placed that allows its input to satisfy only input requests issued 
in the specific-mode. Continue-specific mode is established by 
specifying OPTCD=CS for the RPL used by an OPNDST or any 
I/O macro instruction. 

conversational write operation: A composite operation wherein 
data is first sent to a terminal, and data is then read from that 
terminal. It is implemented with a WRITE macro instruction 
having the CONV option code set in its RPL. 

CS mode: See continue-specific mode. 



error lock: A condition established by the communications 
controller wherein communication with the terminal is suspend- 
ed. The RESET macro instruction is used to reset the error lock. 

exception message: A message that represents another message 
that never arrived, or for which a transmission error occurred. 
Exception messages are not sent by VTAM application programs 
or terminals; messages are sent which either arrive as normal 
messages or are replaced with exception messages. Upon receiv- 
ing an exception message, the application program or terminal 
usually returns an exception response. 

exception response: A response sent by a terminal or applica- 
tion program indicating that a particular message did not arrive 
normally. 

exit list: In VTAM, a control block that contains the names of 
routines that receive control when specified events occur during 
VTAM execution. For example, programs named in the exit list 
handle such conditions as logon processing and I/O errors. 
Abbreviated EXLST. 

EXLST: Exit list. 

exit-routine: A routine whose address has been placed in an exit 
list (EXLST) control block. The addresses are placed there with 
the EXLST macro instruction, and the routines are named 
according to their corresponding operand; hence DFASY exit- 
routine, TPEND exit-routine, RELREQ exit-routine, and so 
forth. All exit-routines are coded by the application program- 
mer. Contrast withi?PL exit-routine. 



FME response: A response that indicates whether its associated 
message was or was not successfully forwarded to its final 
destination (such as the display screen of an output device). 

I 

inactive: Pertaining to a node that is neither connected to nor 
available for connection to another node. 



data transfer: In telecommunications, the sending of data from 
one node to another. 

definition statement: The means of describing an element of 
thetelecommunication system to VTAM. 

device-control character: A control character that is embedded 
in a data stream to control mechanical and format operations at 
a terminal (for example, a line-feed charactcharacter or carriage- 
return character). Contrast with line-control character. 

device-dependent: A characteristic of VTAM such that the 
application program is responsible for controlling the terminal to 
which it is connected. The application program is not responsible 
for controlling the use of the line by which the terminal is 
attached. 

disconnection: In VTAM, the disassociation of VTAM control 
blocks in such a way as to end communication between the 
program and a connected terminal. The disconnection process 
includes suspending the use of the network path between the 
program and the terminal. It is implemented with the CLSDST 
macro instruction. 



interpret table: In VTAM, an installation-defined correlation list 
that translates an argument into a string of eight characters. 
Interpret tables can be used to translate a logon message into the 
name of an application program for which the logon request is 
intended. 

input opjeration: In VTAM, an operation that obtains input 
from a terminal connected to the application program. Input 
operations are implemented by RECEIVE, READ, and SOLICIT 
macro instructions, and by the conversational variation of 
WRITE macro instructions. 



leading graphics: From one to seven graphic characters that may 
accompany an acknowledgment sent to or from a BSC terminal 
in response to the receipt of a block of data. 



line: The communication medium linking a communication 
control unit to another communication control unit, or linking a 
communication control unit to one or more terminals. 
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line-control character: A character in a data stream that controls 
the transmission of data over a network path; for example, 
line-control characters delimit messages and indicate whether a 
node has data to send or is ready to receive data. 

line-control discipline: A general term for the set of rules, 
requirements, and procedures for transmitting information to 
and from a particular type of terminal in a telecommunication 
system. 

line group: A set of one or more lines of the same type. 

local: Pertaining to terminals and communication control units 
that are attached directly by channels to a central computer. 

logical device order: In VTAM, a set of parameters that specify 
a data-transfer or data-control operation. Abbreviated LDO. 

logical error: An error that results from an invalid request. 

logical unit: The combination of programming and hardware of 
a teleprocessing subsystem that comprises a terminal for VTAM. 

logoff request: A request by a terminal user to be disconnected 
from an application program. 

logon message: In VTAM, the data that can accompany a logon 
request received by the application program to which the request 
is directed. 

logon request: A request for connection between a terminal and 
an application program that is initiated by or on behalf of the 
terminal. 

M 

message: (1) For logical units, the unit of information (data or 
indicators) that is sent by an application program or logical unit 
on its own initiative. Contrast with responses, which are sent 
only in reply to messages that have been received. (2) For BSC 
devices, the data unit from the beginning of a transmission to the 
first ETX character, or between two ETX characters. For 
start/stop devices, "message" and "transmission" have the same 
meaning. 

N 

NCP: See network control program. 

NCP generation: See network control program generation. 

negative polling limit: The maximum number of consecutive 
negative responses to polling that the communications controller 
will accept before suspending polling operations. 

network control program: A program, transmitted to and stored 
in a communications controller, that controls the operation of 
the communications controller. Abbreviated NCP. 

network control program generation: The process, performed in 
a central processing unit, of assembling and link-editing a macro 
instruction program to produce a network control program. 

network operator: The person responsible for controlling the 
operation of the telecommunication network. 

NIB: Node Initialization Block. 

NIB list: In VTAM, a series of contiguous NIBs (node initiali- 
zation blocks). 

node: In VTAM, an addressable point in a telecommunication 
system. Nodes include terminal components, terminal control 
units, teleprocessing programs, and remote computers. 



node initialization block: A control block, associated with a 
particular node that contains information used by the appli- 
cation program to identify a node and indicate how communi- 
cation requests directed at the node are to be implemented. 
Abbreviated NIB. 

node name: In VTAM, the symbolic name associated with a 
specific node and assigned during network definition. 

O 

ordinary closedown: In a telecommunications system, the order- 
ly deactivation of a telecommunication access method and 
network. In VTAM, an ordinary closedown does not take effect 
until all application programs have disconnected their terminals 
and closed their ACBs. Until then, all data-transfer operations 
continue, but VTAM rejects any further attempts to open ACBs. 
Contrast with quick closedown. 

option code: One of the indicators set by the OPTCD operand 
of the RPL macro instruction. These indicate how a given 
request is to be implemented by VTAM. 



physical error: An error that is not the result of an error in the 
design of the application program. 

processing option: One of the indicators set by PROC operand 
of the NIB macro instruction. These indicate how communi- 
cation requests are to be implemented for a given terminal. 



QC indicator: See quiesce-completed indicator. 
QEC indicator: See quiesce-at-end-of-chain indicator. 

queued for logon: In VTAM, the state of a terminal that has 
logged on to an application program but has not yet been 
accepted for connection by that application program. Contrast 
with connection. 

queued logon request: A logon request that has been directed at 
an application program but not yet accepted by that application 
program. Logon requests are queued with the OPNDST 
(OPTCD=ACCEPT) and SIMLOGON macro instructions. 

quick closedown: In VTAM, a closedown in which current 
data-transfer operations are completed, while pending 
data-transfer requests and new connection and data-transfer 
requests are canceled. Contrast with ordinary closedown. 

quiesce-at-end-of-chain (QEC) indicator: An indicator sent by 
one node to another indicating that the other node should stop 
transmitting synchronous-flow messages after it has sent the last 
record of the chain being transmitted. 

When the other node returns a QC indicator, it cannot again 
transmit synchronous-flow messages until a RELQ indicator is 
received from the first node. A QEC indicator is sent when a 
SEND macro instruction is issued with CONTROL=QEC set in 
its RPL. 

quiesce-completed (QC) indicator: An indicator sent by a node 
indicating that it will not transmit synchronous-flow messages 
again until it receives a RELQ indicator from the other node. A 
QC indicator is sent when a SEND macro instruction is issued 
with CONTROL=QC set in its RPL. 

quiesce communication: A method of communicating in one 
direction at a time. Using this method, either node can assume 
the exclusive right to send synchronous-flow messages by getting 
the other node to aeree not to send such messages. When the 



Glossary 279 



quiescing node wants to receive, it can release the other node 
from its quiesced state, allowing that node to send. 

quiescing: In a VTAM application program, a way for one node 
to stop another node from sending synchronous-flow messages. 
Quiescing requires the sending of a quiesce-at-end-of-chain 
(QEQ indicator and can include the receiving of a 
quiesce-completed (QC) indicator. Sending by the quiesced node 
can be restarted by the quiescing node sending a release- 
indicator. Among other reasons, quiescing can be used to: (1) 
ensure a communication pattern in which only one node can 
send at a time, (2) stop the continuous sending of data by one 
node because a buffer in the other node is about to overflow, or 
(3) occasionally interrupt continuous sending of data by one 
node so that output can be sent by the other node. 



RPL-based macro instruction: A macro instruction whose para- 
meters are specified by the user in an RPL. For all RPL-based 
macro instructions, the user must specify the address of the 
RPL. All RPL-based macro instructions except CHECK permit 
RPL-modifying operands to be specified with the macro instruc- 
tion. Figure 1 lists the RPL-based macro instructions. 

RPL exit-routine: A routine whose address has been placed in 
the EXIT field of an RPL. For asynchronous requests, this 
routine is automatically invoked by VTAM when the request 
associated with the RPL is completed. Contrast with 
exit-routine. 

RRN response: A response that indicates that the node sending 
the response has accpeted recovery responsibility for the 
associated message. 



RDT: Resource definition table. 

read operation: The transfer of data from VTAM buffers to 
program storage. 

read request: Any request for a read operation. Read requests 
are implemented with RECEIVE or READ macro instructions, 
WRITE macro instructions if OFTCD=CONV is used, or DO 
macro instructions if READ LDOs are used. 

record: The unit of data transmission for record-mode. A record 
represents whatever amount of data the transmitting node 
chooses to send. 

record-mode: A set of facilities (and the macro instructions 
needed to use them) that enable the application program to 
communicate with logical units or with the locally or remotely 
attached 3270 Information Display System. SEND, RECEIVE, 
and RESETSR are record-mode macro instructions. 

release-quiesce (RELQ) indicator: An indicator sent by a node 
indicating that the other node can begin transmitting 
synchronous-flow messages. A RELQ indicator is sent when a 
SEND macro instruction is issued with CONTROL=RELQ set in 
its RPL. 

RELQ indicator: See release-quiesce indicator. 

remote: Pertaining to terminals and communication control 
units that are attached to a central computer through a 
communication control unit. 



scheduled output: A type of output request that is completed 
(as far as the application program is concerned) when its output 
data area is free. Contrast with responded output. Scheduled 
output occurs if POST=SCHED is specified for the RPL used by 
a SEND macro instruction. 

SDT indicator: See start-data-traffic indicator. 

sequence number: A numerical value assigned by VTAM to each 
message exchanged between two nodes. The value (one for 
messages sent from the application program to the logical unit, 
another for messages sent from the logical unit to the application 
program) increases by one for each successive message trans- 
mitted. The value increases by one throughout the life of the 
connection unless reset by the application program with an 
STSN signal. 

session: In the communication controller's Network Control 
Program, , series of command and data interchanges between the 
host processor and a teleprocessing device. 

session limit: In the communication controller's Network 
Control Program, the maximum number of concurrent sessions 
that can be initiated on a multipoint line. 

SESSIONC indicators: Indicators that can be sent from one 
node to another without using SEND or RECEIVE macro 
instructions. SDT, clear, and STSN are SESSIONC indicators. All 
SESSIONC indicators are sent with a SESSIONC macro 
instruction. 



request parameter list: A control block that contains the 
parameters necessary for processing a request for data transfer or 
a request for connecting or disconnecting a node. Abbreviated 
RPL. 

resource definition table: In VTAM, a table that describes the 
characteristics of each node available to VTAM and associates 
each node with an address. The resource definition table is built 
during VTAM definition with APPL, LINE, GROUP, LU, and 
TERMINAL macro instructions, but it can be modified by the 
network operator while VTAM is running. Abbreviated RDT. 

responded output: A type of output request that is completed 
when the logical unit receives the message and returns a response 
(if one is called for) for it. Responded output occurs if 
POST=RESP is specified for the RPL used by a SEND macro 
instruction. 

response: The unit of information that is sent by an application 
program or terminal in reply to a message that has been received. 

RPL: Request parameter list. 



set-and-test-sequence-number (STSN) indicators: A set of 
SESSIONC indicators sent by one node to another to establish 
the proper sequence number. 

shared: (1) Pertaining to communication control units and 
communications lines that may be used concurrently by several 
teleprocessing programs to communicate with different nodes. 
(2) Pertaining to terminals that may be used by more than one 
teleprocessing program; only one teleprocessing program may be 
connected to a shared terminal at any one time. 



simulated logon request: A request initiated by a program (via 
the SIMLOGON macro instruction) on behalf of a device, for 
connection between the device and a program. Contrast with 
logon request and automatic logon request. 

solicit operation: The process of obtaining (or attempting to 
obtain) data from a device and moving that data into VTAM 
buffers. 

solicit request: Any request for a solicit operation. There are 
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three such requests: (1) A SOLICIT macro instruction; (2) a 
READ macro instruction, if the SPEC option is in effect and if 
VTAM buffers hold no data from the device being read from; 
and (3) a WRITE macro instruction with the CONV option code 
set. 

specific-mode: (1) The form of READ, RECEIVE, or SOLICIT 
operation that obtains data from one specific terminal, or (2) the 
form of OPNDST operation that establishes connection with one 
specified terminal if (or when) a logon request is received from 
that terminal. Specific-mode is established by specifying 
OPTCD=SPEC for the RPL used by the READ, RECEIVE, 
SOLICIT, or OPNDST macro instructions. 

start-data-traffic (SDT) indicator: SESSIONC indicator sent by 
one node to another that enables data flow between them. 

STSN indicator: See set-and-test-number indicators. 



transmission: In telecommunications, a logical group of one or 
more blocks or messages. For BSC and start-stop devices, a 
transmission is terminated by an EOT character. Contrast with 
block and message. 

transmission limit: The number of transmissions that can be 
sent to or received from a teleprocessing device during the 
servicing of one session on a multipoint line (or point-to-point 
line where the terminal has multiple components) before the 
Network Control Program suspends the session to service other 
sessions on the line. 

transparent text mode: A mode of binary synchronous trans- 
mission in which only line control characters preceded by DLE 
are acted upon as line control characters. All other bit patterns 
that happen to be line control characters are transmitted as data. 

V 



synchronous-flow message: Messages that can satisfy a RE- 
CEIVE macro instruction only if no asynchronous-flow messages 
are available to satisfy the macro instruction. (The RECEIVE 
macro instruction in this definition is one which can be satisfied 
by either type of message.) 

synchronous request: A request that causes control to be 
returned to the application program only after the requested 
operation has been completed. A request is made synchronous 
by setting the SYN option code in its RPL. Contrast with 
asynchronous request. 



telecommunication network: In a telecommunication system, 
the combination of all terminals and other telecommunication 
devices and the lines that connect them. 

telecommunication system: In a teleprocessing system, those 
devices and functions concerned with the transmission of data 
between the central processing system and the remotely located 
users. In VTAM, the telecommunication system includes the 
host CPU, application programs using VTAM, VTAM, the 
telecommunication network, and the channels that link the host 
CPU and the network. 



Virtual Telecommunications Access Method: A set of IBM 

programs that control communication between terminals and 
application programs running under DOS/VS, OS/VS1, and 
OS/VS2. 

VTAM: Virtual Telecommunications Access Method. 

VTAM definition: The process of (1) including VTAM in the 
operating system generation (SYSGEN), (2) defining the tele- 
processing network to VTAM and communication controller's 
Network Control Program, and (3) modifying IBM-defined 
VTAM characteristics to suit the needs of the installation. 
VTAM definition is implemented by the installation with 
definition macro instructions and operator commands. 

W 

write operation: The transfer of data from program storage to a 
device. A write operation is implemented with a SEND, WRITE, 
or DO macro instruction. 



teleprocessing subsystem: In VTAM, a secondary or subordinate 
network (and set of programs) that is part of a larger 
teleprocessing system; for example, the combination consisting 
of SDLC cluster controller, its stored program, and its attached 
input/output devices. 

An example of a teleprocessing subsystem is the IBM 3600 
Finance Communication System. 

teleprocessing system: The devices and functions of a data 
processing system that enable users at remote locations to access 
the data processing capabilities of a centrally located computer. 
A teleprocessing system has two major functions: the trans- 
mission of data between the central computer and the remote 
locations (performed by the telecommunication system) and the 
actual processing of the data in the central computer. 

terminal: A node in a telecommunication network at which data 
can enter or leave the network. A terminal can be an 
input/output device, a terminal control unit to which one or 
more input/output devices (terminal components) are attached, 
a logical unit, or a remote station. ("Terminal" is generally used 
when its context applies to both BSC and start-stop terminals 
and to logical units.) 

terminal component: A separately addressable part of a terminal 
that performs an input or output function. 

terminal-initiated logon request: A logon request that originates 
from the terminal 
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AARE A operand 108 
AAREALN operand 108 
ACB 

DSECT (IFGACB) 232 

format (DOS/VS) 230 

format (OS/VS) 231 

macro instruction 12 
ACB address operand 

of the CLOSE macro instruction 19 

of the OPEN macro instruction 76 
ACB operand 

of the MODCB macro instruction 62 

of the RPL macro instruction 106 

of the SHOWCB macro instruction 145 

of the TESTCB macro instruction 1 5 5 
ACB-briented exit-routines 66 
ACBLEN operand value 157,43 
ACCEPT, explanation of 79 
ACCEPT operand value 1 14 
accepting logon requests 79 
access method control block (ACB) 

definition of 277 

DSECT (IFGACB) 232 

explanation of 12 

format (DOS/VS) 230 

format (OS/VS) 231 
ACQUIRE, explanation of 79 
ACQUIRE o perand value 1 1 4 
acquiring terminals 79 
action code 

for inbound sequence number 1 39 

for outbound sequence number 139 
active application program, testing for 48 
ADDR operand 58 
"address" notation category 212 
AID (attention identification) 265 
allowing LOGON exit-routine scheduling to begin 141 
allowing LOGON exit-routine scheduling to resume 141 
AM operand 

of the ACB macro instruction 12 

of the EXLST macro instruction 30 

of the MODCB macro instruction 61 

of the RPL macro instruction 106 

of the SHOWCB macro instruction 145 

of the TESTCB macro instruction 1 54 
ANY operand value 114 
any-mode 277 
application program 

availability of 45 

definition of 277 

determining logon queuing status of 45 

opening of 75 

termination of 19 
APPL entry 12 

APPL operand value (for SDT=) 66 
APPLID operand 12 
APPSTAT operand value 48 
AREA operand 

of the RPL macro instruction 106 

of the SHOWCB macro instruction 146 
AREALEN operand 107 
ARECLEN field 121 
ARECLEN operand value 147,157 
ARG field 122 

assembler format tables, explanation of 7 
AS Y operand value 118 
asynchronous request handling 175 
attention interruption 



handling 40 

monitoring 72 
ATTN operand 40 
AT&T Teletypewriter Terminal 259 
AT&T 83B3 Selective Calling Station 
authorization 

to acquire a terminal 79 

to pass a connection 22 

to use the BLOCK processing option 
automatic logon requests 277,37 
available application program 45 
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BASIC operand value 65 
basic-mode macro instructions 

CHANGE 15 

DO 26 

LDO 54 

READ 85 

RESET 96 

SOLICIT 151 

WRITE 159 
BB operand value 

following RECEIVE 94 

for SEND 131 
bid indicator, sending 1 30 
BID operand value 1 30 
BINARY operand value 72 
bit setting (DSECT definition) 229 
BLK operand of the GENCB macro instruction 41 
BLK operand value of the RPL macro instruction 161 
BLOCK operand value 

explanation of 70 

illustration of use of 69 
block of data 

sent 159 

solicited 151 
braces, use of (as notational symbols) 9 
brackets, use of (as notational symbols) 9 
bracket indicators 

receiving 94 

sending 131 
BRACKET field 

following RECEIVE 94 

for SEND 131 
BRANCH operand 109 
branching table, use of with 

recovery action (RTNCD) return codes 177 

specific error (FDBK2) return codes 181 

TESTCB return codes 155 
BSCID operand value 50 
byte value (DSECT definition ) 229 

C operand value (LDO) 59 

CA operand value 118 

CALL (VTAM definition parameter), effect of during 

connection 79,148 
cancel indicator 

receiving 95 

sending 1 30 
CANCEL field 

following RECEIVE 95 

for SEND 130 
canceling basic-mode I/O requests 96 
canceling RECEIVE requests 101 
categories of macro instructions 3 
CHAIN field 

for RECEIVE 94 

for SEND 131 
chaining LDOs 59 
change-direction indicators 

receiving 94 

sending 131 



Index 283 



CHANGE macro instruction 15 
changing CA-CS mode 118 
changing NIB fields 15 
chase indicator 

receiving 95 

sending 131 
CHASE operand value 

following RECEIVE 95 

for SEND 130 
CHECK macro instruction 17 
checking event completion status 

by using the CHECK macro instruction 17 

by using the feedback fields 181 
CHNGDIR operand 

following RECEIVE 94 

for SEND 131 
CID field 

definition of 278 

explanation of 63 
CID operand value 147 
CIDXLATE operand value 49 
clear indicator , sending 138 
CLEAR operand value 138 
clearing RPLs 17 
CLOSE macro instruction 19 
closedown 35 
closing an ACB 19 
closing a logon queue 141 
CLSDST macro instruction 22 
CMD operand (for LDO) 55 
CMD operand value 

following RECEIVE 94 

for SEND 131 
commands, LDO 55 
comments, coding 10 

Communicating Magnetic Card Selectric Typewriter 255 
communicating with terminals 

by reading 85 

by receiving (logical units) 89 

by sending (logical units) 129 

by soliciting 151 

by writing 159 
COMPLETE operand value 157 
component, communication with 

AT&T 83B3 Selective Calling Station 258 

Western Union Plan 1 15 A Station 260 

1050 Data Communication System 251 

2740 Communication Terminal 252,253 
CON field 73 
CONALL operand value 113 
CONANY operand value 113 
COND operand value 97 
condition code 154 

conditional cancelation of basic-mode I/O operations 96 
conditional connection request (Q-NQ) 120 
confidential data handling 68 
CONFTXT operand value 68 
connected terminals, determining number of 45,48 
connecting terminals 79 
CONT operand value 

explanation of 70 

illustration of 69 
continuation lines, how to code 1 
continue-any mode 118 
continue-specific mode 118 
continuous solicitation 68-70 
control block DSECTs 

IFGACB (ACB) 232 

IFGEXLST (EXLST) 234 

IFGRPL (RPL) 238 

ISTDNIB (NIB) 247 

ISTDPROC (PROC field) 250 

ISTDVCHR (DEVCHAR field) 248 

ISTUSFBC (FDBK2 field) 242 



control block field lengths 147 

control block field testing 154 

control block formats 
ACB (DOS/VS) 230 
ACB (OS/VS) 231 
EXLST 233 
LDO 54 
NIB 246 
RPL (DOS/VS) 235 
RPL (OS/VS) 236 

control block generation 

during INQUIRE processing 45 
during program execution 41 
with the ACB macro instruction 12 
with the EXLST macro instruction 29 
with the GENCB macro instruction 41 
with the LDO macro instruction 54 
with the NIB macro instruction 63 
with the RPL macro instruction 104 

control block lengths (see Appendix H) 

control block manipulation 
general 5 
with DSECTs 229 
with the GENCB macro instruction 41 
with the MODCB macro instruction 61 
with the SHOWCB macro instruction 145 
with the TESTCB macro instruction 154 

control block usage, table of 163 

CONTROL field 
for RECEIVE 95 
for SEND 130 
for SESSIONC 138 

CONV o perand value 161 

conversational write operation 159 

converting a CID to a symbolic name 49 

converting a symbolic name to a CID 49 

COPIES operand 42 

copy control character 55 

COPYLBM operand value 55 

COPYLBT operand value 55 

COUNTS operand value 48 

CPM error 204 

CS operand value 118 

D operand value (LDO) 59 
DATA operand value 

following RECEIVE 95 

for SEND 130 
data security 68 
DATAFLG return codes 201-202 
DCBs (data control blocks) 

closing 19 

opening 76 
DEVCHAR field DSECT (ISTDVCHR) 248 
DEVCHAR field format 246 
DEVCHAR operand value 47 
device characteristics 251-276 
devices supported by VT AM 251-276 
DFASY exit-routine 32 
DFASY input, applicable RPL fields for 93 
DFASY operand value 

for RECEIVE 92 

for RESETSR 102 
DFASYX processing option 67 
DFSYN input, applicable RPL fields for 93 
DFSYN operand value 

for RECEIVE 92 

for RESETSR 102 
dial-in terminals, connecting 148 
dial-line terminals, connecting 148,79 
dial-line disconnection 39 
dial-out terminals, connecting 79 
DISCONCT LDO 58 
disconnecting terminals 22 
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DO macro instruction 26 

DSECTs 

general 229 
IFGACB (ACB) 232 
IFGEXLST (EXLST) 234 
IFGRPL (RPL) 238 
ISTDNIB (NIB) 247 
ISTDPROC (PROC field) 250 
ISTDVCHR (DEVCHAR field) 248 
ISTUSFBC (FDBK2 field) 242 

DTFs (define-the-file control blocks) 
closing 19 
opening 76 

EAULDO 58 

EAU operand value 161 

EB operand value 

following RECEIVE 94 

for SEND 131 
ECB operand 108 
ECB posting 175 
EIB operand value 71 
ELC operand value 72 
ellipsis, use of 9 

end of intermediate transmission block 
161 
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ERASE operand value 
ERASELBM LDO 58 
ERASELBT LDO 58 
erasing a display screen 1 6 1 ,5 8 
erasing unprotected data 161,58 
ERET operand 155 
ERPIN operand value 72 
ERPOUT operand value 72 
ERROR field 

use of after CLOSE processing 20 

use of after OPEN processing 77 
error handling 

by exit-routines 30-32 

using the FDBK2 field 1 82-201 
error information byte (EIB) 71 
error lock 

definition 278 

resetting 96 
ERROR operand value 147,157 
error recovery messages 

2770 Data Communication Terminal 261 

3780 Data Transmission Terminal 274 
error recovery procedures, suppression of 72 
error return information (see return codes) 
event control block (ECB) 108 
EX operand value 

following RECEIVE 93 

for SEND 133 
exception message 186 
exception response 

receiving 1 86 

sending 133 
excess data, saving 68,113 
EXECRPL macro instruction 28 
execute form 

general 219 

of the GENCB macro instruction 222 

of the MODCB macro instruction 223 

of the SHOWCB macro instruction 224 

of the TESTCB macro instruction 225 
executing RPLs 28 
exit list 

creation 29 

definition 278 
exit-routine 



ATTN 40 
definition of 
DFASY 32 
LERAD 30 



LOGON 37 

LOSTERM 39 

RELREQ 36 

RESP 33 

RPL 109 

SCIP 34 

SYNAD 31 

TPEND 35 
EXIT operand 109 
EXLLEN operand value 43 
EXLST control block 29 
EXLST DSECT (IFGEXLST) 234 
EXLST format 233 
EXLST macro instruction 29 
EXLST operand 

of the ACB macro instruction 1 3 

of the MODCB macro instruction 62 

of the NIB macro instruction 66 

of the SHOWCB macro instruction 145 

of the TESTCB macro instruction 155 
extracting control block fields 145 

FDBK return codes 

for INQUIRE (OPTCD=APPSTAT) 202 

for READ, WRITE, and DO 201 
FDBK operand value 213 
FDBK2 DSECT (ISTUSFBC) 242 
FDBK2 operand value 213 
FDBK2 return codes 1 85-201 
feedback fields (see Appendix C) 
field displacement (DSECT definition) 229 
field name operand (for TESTCB) 155 
FIELDS operand 146 
FIRST operand value 

following RECEIVE 94 

for SEND 131 
"fixed value" notation category 216 
FLAGS operand 59 
FME operand value 1 33,93 
FME response sending 1 33 
FMHDR option code 113 

Form Description Program (FDP) data blocks 271 
"from" device 268 
Function Interpreter error 204 
Function Management Header 113 

GENCB macro instruction 4 1 

general poll 151 

general return code (register 15) 177 

generate form 
general 219 

of the GENCB macro instruction 222 
of the MODCB macro instruction 223 
of the SHOWCB macro instruction 224 
of the TESTCB macro instruction 225 

generating control blocks 

during program assembly (see ACB, EXLST, RPL, NIB, 

and LDO) 
during program execution 41 

GETMAIN facility 41 

GETVIS facility 41 

graphic characters, leading 
definition of 278 
receiving 71 
sending 57 

group mode 

AT&T 83B3 Selective Calling Station 258 
Western Union Plan 115A Station 260 
1050 Data Communication System 251 
2740 Communication Terminal 252,253 
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HALT command 35 
Header, Function Management 
heading block 57 
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high-priority I/O request handling (OS/VS2) 109 

IBSQAC operand 139 

IBSQVAL operand 138 

ID verification 50 

IFGACB DSECT 232 

IFGEXLST DSECT 234 

IFGRPL DSECT 238 

implicit solicitation 85 

inactive application program 48 

inactive RPL 17 

inbound sequence number 138 

inbound sequence number action code 139 

inbound STSN indicators 139 

indicators, sending 130 

INQUIRE macro instruction 45 

input area 106 

input area too small 185 

input operations 

reading 85 

receiving 89 

soliciting 151 
installation authorization 

to acquire a terminal 79 

to pass a connection request 22 

to use the BLOCK processing option 70 
intermediate transmission block (ITB) 71 
interpret table 51 
interpreting an input'sequence 5 1 
interpreting the feedback fields (see Appendix C) 
INTRPRET macro instruction 5 1 
IO operand 157 
I/O operations 

cancelation of (basic-mode) 96 

cancelation of (record-mode) 100 

conversational 161 

input (basic-mode) 85,151 

input (record-mode) 89 

output (basic-mode) 159 

output (record-mode) 129 
IPL, remote (System/7) 257 
isolating terminals from READ requests 118 
ISTDNIB DSECT 247 
ISTDPROC DSECT 250 
ISTDVCHR DSECT 248 
ISTUSFBC DSECT 242 
ITB 71 

KEEP operand value 68,1 13 
keyword operands 7 

LAST operand value 

following RECEIVE 94 

for SEND 131 
LBM operand value 161 
LBT operand value 161 
LDO commands 

COPYLBM 55 

COPYLBT 55 

DISCONCT 58 

ERASELBM 

ERASELBT 

EAU 58 

READ 55 

READBUF 

WRITE 56 

WRITELBM 56 

WRITELBT 57 

WRTHDR 57 

WRTNRLG 57 

WRTPRLG 57 
LDO control block 54 
LDO macro instruction 54 
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leading graphic characters, 

receiving 71 

sending 57 
LEN operand 58 
length of control block fields 147 
length of control blocks (see Appendix H) 
LENGTH operand 

of the GENCB macro instruction 42 

of the SHOWCB macro instruction 146 
LERAD exit-routine 30 
LERAD operand 30 
LGIN operand value 71 
LGOUT operand value 70 
limits for operand values 10 
line control characters 

generated or recognized by VTAM 171 

suppression of 72 
list form 

general 219 

of the GENCB macro instruction 222 

of the MODCB macro instruction 223 

of the SHOWCB macro instruction 224 

of the TESTCB macro instruction 225 
LISTEND operand 65 
lists of NIBs 

creation of 65,48 

explanation of 63 
LOCK operand value 98 
logical device order (LDO) 

definition of 279 

description of 54 
logical errors 

definition of 279 

listing of 191-201 

routine to handle (LERAD) 
logical unit macro instructions (see RECEIVE, RESETSR, SEND, 

and SESSIONC) 
logical unit sense fields 203 
logical-unit-status (LUS) indicator 

receiving 95 

sending 131 
LOGON exit-routine scheduling 

initiating 141 

terminating 141 
LOGON operand of the EXLST macro instruction 37 
LOGON operand value (ACB) 1 3 
LOGONMSG operand value 47 
logon messages 

receiving 45 

sending 24 
logon requests 

determining the number of 45 

handling of 37 

queuing of 120 
logon status modification 14 1 
LOSTERM operand 39 
LUS operand value 

following RECEIVE 95 
for SEND 131 

MACRF operand 13 

macro instruction categories 3 

macro instruction descriptions 

ACB 12 

CHANGE 15 

CHECK 17 

CLOSE 19 

CLSDST 22 

DO 26 

EXECRPL 28 

EXLST 29 

explanation of 7 

GENCB 41 
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INQUIRE 45 

INTRPRET 51 

LDO 54 

MODCB 61 

NIB 63 

OPEN 75 

OPNDST 79 

READ 85 

RECEIVE 89 

RESET 96 

RESETSR 100 

RPL 104 

SEND 129 

SESSIONC 136 

SETLOGON 141 

SHOWCB 145 

SIMLOGON 148 

SOLICIT 151 

TESTCB 154 

WRITE 159 
manipulating control blocks 

general 5 

with DSECTs 229 

with the GENCB macro instruction 4 1 

with the MODCB macro instruction 61 

with the SHOWCB macro instruction 145 

with the TESTCB macro instruction 154 
messages 

sending 161 

soliciting 70 
MF operand 

of the GENCB macro instruction 43 

of the MODCB macro instruction 62 

of the SHOWCB macro instruction 146 

of the TESTCB macro instruction 155 
MIDDLE operand values 

following RECEIVE 94 

for SEND 131 
MODCB macro instructions 61 
MODE operand 65 
modifying control blocks 5 
MONITOR operand value 72 
monitoring attention interruptions 72 
MSG operand value 70 
MSG option, illustration of 69 
multiple control block generation 42 
multiple request parameter lists (RPLs) 104 

NAME operand 64 
NBB operand value 

following RECEIVE 94 

for SEND 131 
NBINARY operand value 72 
NCMD operand value 

following RECEIVE 94 

for SEND 131 
NCONFTXT operand value 68 
NCONV operand value 1 6 1 
NCP failure 39,188 
NCP return codes 203 
NDFASY operand value 

for RECEIVE 92 

for RESETSR 102 
NDFASYX processing option 67 
NDFSYN operand value 

for RECEIVE 92 

for RESETSR 102 
NEB operand value 

following RECEIVE 94 

for SEND 131 
negative response, sending (record-mode) 133 
negative response with leading graphics (basic-mode) 
NEIB operand value 71 
NELC operand value 72 



NER ASE operand value 161 

NERPIN operand value 72 

NERPOUT operand vlaue 72 

Network Control Program (NCP) failure 39,188 

NEX operand value 1 33,93 

NFME operand value 133,93 

NFMHDR operand value 1 1 3 

NIB DSECT (ISTDNIB) 247 

NIB field, contrasted with ARG field 106 

NIB format 246 

NIB generation for terminal groups 48 

NIB lists 

creation of 65,48 

explanation of 63 
NIB macro instruction 63 
NIB modifications after OPNDST 15 
NIB operand 

of the MODCB macro instruction 62 

of the RPL macro instruction 106 

of the SHOWCB macro instruction 145 

of the TESTCB macro instruction 155 
NIB-oriented exit-routines 66 
NIBLEN operand value 43 
NIBTK option code 43 
NLGIN operand value 71 
NLGOUT operand value 70 
NLOGON operand value 1 3 
NMONITOR operand value 72 
no input available 185 
node initialization block (NIB) 

definition of 279 

explanation of 63 
NQ operand value 120 
NRELRQ operand value 150 
NRELRQ used for the RELREQ exit-routine 150 
NREQ operand value 

following RECEIVE 94 

for SEND 131 
NRESP operand value 

for RECEIVE 92 

for RESETSR 102 
NRESPX processing option 68 
NRRN operand value 1 3 3 ,9 3 
NTIMEOUT operand value 7 1 
NTMFLL operand value 71 

OBSQAC operand 139 
OBSQVAL operand 138 
OFLAGS field testing 20,76 
OFLAGS operand 157 
ONLY operand value 

following RECEIVE 94 

for SEND 131 
open destination 79 
OPEN macro instruction 75 

OPEN operand value of the TESTCB macro instruction 
opening ACBs 75 
opening a logon queue 141 
operand limits 10 
operand specifications 10 
OPNDST macro instruction 79 
OPTCD operand 112 
option codes 112-121 
options, processing 67-72 
outbound sequence number 138 
outbound sequence number action code 1 39 
outbound STSN indicators 139 
output area 106 
output operation 129,159 
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parameter lists for exit-routines 
PASS operand value 24 
passing terminal connections 22 
PASSWD operand 13 
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password protection 1 3 

PATH error 204 

pending logon requests, determining the number of 48 

physical errors 

listing of 185-191 

routine to handle 3 1 
polling, general 151 
positional operands 9 

positive response, sending (record-mode) 133 
positive response with leading graphics (basic-mode) 57 
POST operand 131 
preventing logon request queuing 

after OPEN processing 14 1 

during OPEN processing 13 
PROC field DSECT (ISTDPROC) 250 
PROC operand 67 
processing options 

applicability of (per device) 74 

definition of 279 

modification of 15 

specification of 67 
protection of data 68 
PSW condition code 154 

Q operand value 120 
QC operand value 

following RECEIVE 95 

for SEND 130 
QEC operand value 

following RECEIVE 95 

for SEND 130 
"quantity" address category 215 
quick closedown 35 
quiesce-at-end-of-chain (QEC) indicator 

receiving 95 

sending 1 30 
quiesce-completed (QC) indicator 

receiving 95 

sending 130 
QUIESCE operand value 14 1 
queuing of logon requests 141 
queuing of connection requests 120 

read buffer 56 

READ macro instruction 85 

READ operand value (LDO) 55 

read operation 85 

read request, definition of 280 

READBUF operand value (LDO) 56 

ready-to-receive (RTR) indicator, receiving 95 

reason code (FDBK2) 185-201 

RECEIVE macro instruction 89 

receiving data blocks 85 

receiving messages and responses 89 

RECLEN field or operand 107 

RECORD operand value 65 

record-mode macro instructions 

RECEIVE 89 

RESETSR 100 

SEND 129 

SESSIONC 136 
recovery action return code 177 

data integrity damaged 179 

environment error 178,180 

logical error 178,180 

retry appropriate 178,179 

special condition 179 
register and 15 return codes 176 
register notation 110 
register usage 227 
registers, permitted 10 
RELEASE operand value 24 
release-quiesce (RELQ) indicator 

receiving 95 

sending 130 



releasing terminals in the RELREQ exit-routine 36 
releasing terminals, method of 22 
RELQ operand value 

following RECEIVE 95 

for SEND 130 
RELREQ operand value of the RPL macro instruction 150 
RELREQ operand of the EXLST macro instruction 36 
"remote" list form (manipulative macro instructions) 219-220 
REQ field 121 
REQ operand value (CHNGDIR=) 

following RECEIVE 94 

for SEND 131 
request code 121 
request for test messages 

2770 Data Communication System 261 

2780 Data Transmission Terminal 263 

2972 General Banking Terminal System 264 

3 740 Data Entry System 27 3 

3780 Data Transmission Terminal 274 
request parameter list (RPL), 

definition of 280 

description of 104 
request-recovery (RQR) indicator 34 
Request Reject error 204 

request-shutdown (RSHUTD) indicator, receiving 95 
RESET macro instruction 96 
RESETSR macro instruction 100 
resetting 

an ACB's logon queuing status 141 

an error lock 96 

an I/O request 96 

a terminal's CA-CS mode 100 

RECEIVE macro instructions 100 
resource definition table (RDT) 

definition of 280 

use of 12,64 
RESP exit-routine 33 
RESP input, applicable RPL fields for 93 
RESP operand value 

for POST operand 132 

for RECEIVE macro 92 

for RESETSR macro 102 

for STYPE operand (SEND) 1 30 
RESPLIM operand 66 
RESPOND field 

for RECEIVE 93 

for SEND 133 
responded output 132 
response limit 66 
RESPX processing option 68 
resumption of LOGON exit-routine scheduling 141 
retrying RPL-based requests 28 
return codes 

for CLOSE macro instruction 20 

for manipulative macro instructions 207 

for OPEN macro instruction 77 

for RPL-based macro instructions 
FDBK2 182-201 
FDBK (DATAFLG) 201 
posting of 175 
register 178 
register 15 177 
RTNCD 182-201 
SENSE 203 
types of 176 
RPL 

control block 104 

DSECT (IFGRPL) 238 

exit-routine 109 

FDBK2 DSECT (ISTUSFBC) 242 

fields, applicability of (per macro instruction) 126 

fields set by VT AM 121 

format (DOS/VS) 235 

format (OS/VS) 236 

macro instruction ^104 
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62 
145 
155 



93 



109 



138 



operand 

of the MODCB macro instruction 
of the SHOWCB macro instruction 
of the TESTCB macro instruction 
RPLLEN operand value 43 
RRN operand value 133,93 
RRN response, sending an 133 
RTNCD field 121,177,242 
RTYPE field, applicable RPL fields, when set 
RTYPE operand 
for RECEIVE 92 
for RESETSR 102 
RVI received 186 



save area, requirement for 227,29 
SCHED operand value 131 
scheduled output 132 
scheduling priority of I/O requests 
SCIP exit-routine 34 
SDT indicator 

sent after OPNDST 136 

sent with OPNDST 66 
SDT operand 66 
SDT operand value (for CONTROL=) 
security of data 68 
selection 151 

self-initiated logon requests 148 
SEND macro instruction 129 
sending data blocks 159 
sending messages and responses 129 
SENSE field 203 
sense information 

for a basic-mode terminal 203 

for a logical unit 203-206 

for a 3270 device 266,269 
SEQNO field 

for RECEIVE 93 

for SEND 133 
sequence numbers 110,122 
sequence numbers for STSN indicators 
SESSIONC macro instruction 136 
set-and-test-sequence-number (STSN) indicators 
SETLOGON macro instruction 14 1 
SHOWCB macro instruction 145 
SHUTD operand value 1 30 
shutdown-completed (SHUTC) indicator 95 
shutdown (SHUTD) indicator 1 30 
SIGDATA field 124 
signal indicator 95 
SIMLOGON macro instruction 148 
"simple" list form (manipulative macro instructions) 
simulated logon requests 148 



139 



140 



219-220 



151 



152 



SOLICIT macro instruction 
solicitation 

definition of 280 

explanation of 151 

interruption of 96 

specifying extent of 69,70 
solicited data received 

from a specific terminal 

from any terminal 152 
SPEC operand value 1 14 

special conditions (indicated in FDBK field) 201-203 
special conditions (indicated in FDBK2 field) 185-186 
specific error return code explanations 185-201 
specific component mode 

AT&T 83B3 Selective Calling Station 258 

Western Union Plan 1 15A Station 260 

1050 Data Communication System 251 

2740 Communication Terminal 252,253 



specific terminal, request directed at 114 

specifications for operands 10 

SSENSEI field 123 

SSENSEO field 134 

SSENSMI field 124 

SSENSMO field 134 

start-data-traffic (SDT) indicator 1 3 8 

START operand value 141 

STATE error 204 

STOP operand value 14 1 

stopping logon request queuing 141 

storage shortage, temporary 187 

STSN indicators 

possible responses to 140 

receiving 34 

sending 138 
STSN operand value 138 
STYPE operand 130 
suppression of line control characters 
switched-line (dial-line) disconnection 



72 



22 
39 



caused by CLSDST 

exit-routine invoked 
switched-line terminals, 

connecting 79,148 

disconnecting 22 
symbolic name of an application program 
symbolic name of a terminal 64 
S YN operand value 117 
SYNAD exit-routine 31 
SYNAD operand 31 
synchronous request handling 
SYSTEM operand value 66 
system sense information 

explanation of 203-206 

receiving 95 

sending 134 
system sense modifier information 
203-206 



12 



175 



explanation of 


receiving 


95 


sending 


134 


System/3 


275 


System/7 


257 


System/370 


276 



Teleprocessing On-line Test Executive Program (TOLTEP) 
notification of in LOSTERM exit-routine (TRM) 39 
notification of in RELREQ exit-routine 36 



notification of via RPL return code 
temporary storage shortage 187 
TERMS operand value 48 
TESTCB macro instruction 154 
test request messages 39,187 
2770 Data Communication System 
2780 Data Transmission Terminal 
3270 Information Display System 
3780 Data Transmission Terminal 
testing 

control block fields 154 
m ultiple field values 155 
processing options or option codes 
timefill characters, suppression of 71 
timeout limit, suppression of 71 
TIMEOUT operand value 71 
TMFLL operand value 71 
"to" device 268 



187 



261 
263 

266,267 
274 



155 
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TOLTEP 

notification of in LOSTERM exit-routine (TRM) 

notification of in RELREQ exit-routine 36 

notification of via RPL return code 187 
TOPLOGON operand value 49 
TPEND operand 35 
TRANS operand value 

illustration of use of 69 

specification of 70 
translating 

a CID 45 

an input sequence 5 1 

a logon message 5 1 
transmissions 

sending 161 

soliciting 70 
transparent text mode 72 

2770 Data Communication System 261 

2780 Data Transmission Terminal 263 

3740 Data Entry System 273 

3780 Data Transmission Terminal 274 
TRUNC operand value 68,113 
truncating input data 68,113 
TWX 259 



39 



1050 Data Communication System 25 1 
2740 Communication Terminal, Model 1 

2740 Communication Terminal, Model 2 

2741 Communication Terminal 254 
2770 Data Communication System 261 
2780 Data Transmission System 263 
2972 General Banking Terminal System 
3270 Information Display System 

basic-mode 267 

record-mode 265 
3600 Finance Communication System 
3735 Programmable Buffered Terminal 
3740 Data Entry System 273 
3780 Data Transmission Terminal 274 



252 
253 



264 



270 
271 



unavailable application program 
UNCOND operand value 97 
underscores, use of 9 
undersize input area 107,185 
USENSEI field 124 
USENSEO field 134 
USER field 122 
USER operand value 122 
USERFLD operand 64 
user sense information 

explanation of 204 

receiving 95 

sending 1 34 



45 



vertical bar, use of 9 
VSAM-VTAM similarities 



WAREA operand 42 
Western Union Plan 115 A Station 
World Trade Telegraph Station 
WRITE 

LDO 56 

macro instruction 159 

operand value 56 
WRITELBM operand value 
WRITELBT operand value 
writing 

conversational 161 

output only 159 
WRTHDR operand value 
WRTNRLG operand value 
WRTPRLG operand value 
WTTY 256 
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256 



56 

57 



57 
57 
57 
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